@automattic/charts 3.2.0 → 4.1.0

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

@@ -9,11 +9,13 @@ import {
 import { DataContext } from '@visx/xychart';
 import merge from 'deepmerge';
 import { useContext, useRef, useEffect, useState, useMemo } from 'react';
-import { useChartScopeElement, useGlobalChartsTheme } from '../../../providers';
-import { isSafari, resolveCssVariable } from '../../../utils';
+import { useGlobalChartsTheme } from '../../../providers';
+import { ANNOTATION_POINTERS } from '../../../providers/chart-context/private/catalog-pointers';
+import { isSafari } from '../../../utils';
 import LineChartAnnotationLabelWithPopover, {
 	POPOVER_BUTTON_SIZE,
 } from './line-chart-annotation-label-popover';
+import type { AnnotationStyles } from '../../../types';
 import type { LineChartAnnotationProps } from '../types';
 import type { LabelProps } from '@visx/annotation';
 import type { TextProps } from '@visx/text';
@@ -152,17 +154,22 @@ 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 );
 
-	// Deep merge styles to preserve nested object properties
-	const styles = merge( providerTheme.annotationStyles ?? {}, datumStyles ?? {} );
-
-	// 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, scopeElement ) ?? value : value;
+	// Deep merge to preserve nested object properties. Pointers first, so a per-datum color wins.
+	// Memoized because the result is spread into the visx annotation parts: a fresh object every
+	// render would give each of them new props whether or not a style changed.
+	const styles = useMemo(
+		() =>
+			merge.all( [
+				ANNOTATION_POINTERS,
+				providerTheme.annotationStyles ?? {},
+				datumStyles ?? {},
+			] ) as AnnotationStyles,
+		[ providerTheme.annotationStyles, datumStyles ]
+	);
 
 	// Measure the label height once after initial render
 	useEffect( () => {
@@ -269,14 +276,8 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 	return (
 		<g data-testid={ testId }>
 			<Annotation x={ x } y={ y } dx={ dx } dy={ dy }>
-				<Connector { ...styles?.connector } stroke={ resolveColor( styles?.connector?.stroke ) } />
-				{ subjectType === 'circle' && (
-					<CircleSubject
-						{ ...styles?.circleSubject }
-						fill={ resolveColor( styles?.circleSubject?.fill ) }
-						stroke={ resolveColor( styles?.circleSubject?.stroke ) }
-					/>
-				) }
+				<Connector { ...styles?.connector } />
+				{ subjectType === 'circle' && <CircleSubject { ...styles?.circleSubject } /> }
 				{ subjectType === 'line-vertical' && (
 					<LineSubject
 						min={ yMax }
@@ -312,8 +313,6 @@ 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/line-chart/test/crosshair-style-types.test.ts

@@ -0,0 +1,31 @@
+import type { LineChartProps } from '../types';
+
+type Crosshairs = NonNullable< LineChartProps[ 'withTooltipCrosshairs' ] >;
+
+describe( 'line chart crosshair style types', () => {
+	test( 'accepts paint attributes', () => {
+		const crosshairs: Crosshairs = { verticalStyle: { stroke: 'purple', strokeWidth: 2 } };
+
+		expect( crosshairs.verticalStyle?.stroke ).toBe( 'purple' );
+	} );
+
+	test( 'reserves geometry attributes for the chart', () => {
+		const crosshairs: Crosshairs = {
+			// @ts-expect-error Crosshair coordinates are computed from the active datum.
+			verticalStyle: { x1: 12 },
+		};
+
+		const transformedCrosshairs: Crosshairs = {
+			// @ts-expect-error Crosshair transforms are not paint attributes.
+			verticalStyle: { transform: 'translate(100 0)' },
+		};
+		const transformedStyles: Crosshairs = {
+			// @ts-expect-error Inline crosshair styles accept only paint properties.
+			horizontalStyle: { style: { transform: 'translateX(100px)' } },
+		};
+
+		expect( crosshairs ).toBeDefined();
+		expect( transformedCrosshairs ).toBeDefined();
+		expect( transformedStyles ).toBeDefined();
+	} );
+} );

package/src/charts/line-chart/test/default-tooltip-formatting.test.tsx

@@ -0,0 +1,74 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { GlobalChartsProvider } from '../../../providers';
+import LineChart, { renderDefaultTooltip } from '../line-chart';
+import type { DataPointDate } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// The instant below is Aug 2 in Los Angeles and Aug 3 in Tokyo, so a tooltip
+// that reads the runtime zone prints a different day from the axis.
+
+const date = new Date( '2026-08-02T15:30:00Z' );
+
+const params = {
+	tooltipData: {
+		nearestDatum: { key: 'Series A', datum: { date, value: 10 }, index: 0, distance: 0 },
+		datumByKey: { 'Series A': { key: 'Series A', datum: { date, value: 10 }, index: 0 } },
+	},
+} as unknown as RenderTooltipParams< DataPointDate >;
+
+describe( 'renderDefaultTooltip date heading', () => {
+	it( 'uses the locale and time zone from the provider', () => {
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				{ renderDefaultTooltip( params ) }
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( '3.8.2026' ) ).toBeInTheDocument();
+	} );
+
+	it( 'falls back to the runtime locale and zone when the provider supplies none', () => {
+		render( <GlobalChartsProvider>{ renderDefaultTooltip( params ) }</GlobalChartsProvider> );
+
+		expect( screen.getByText( '8/2/2026' ) ).toBeInTheDocument();
+	} );
+
+	// The tooltip renders through a portal, so this is the only check that the
+	// provider's context actually reaches it inside a real chart.
+	it( 'reaches the tooltip a mounted chart opens', async () => {
+		const user = userEvent.setup();
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<LineChart
+					width={ 500 }
+					height={ 300 }
+					withGradientFill={ false }
+					data={ [
+						{
+							label: 'Series A',
+							data: [
+								{ date, value: 10 },
+								{ date: new Date( date.getTime() + 24 * 60 * 60 * 1000 ), value: 20 },
+							],
+							options: {},
+						},
+					] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( '3.8.2026' );
+	} );
+} );

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

@@ -104,6 +104,106 @@ describe( 'LineChart', () => {
 		);
 	};
 
+	test.each( [ 'auto', 'below-axis' ] as const )(
+		'passes custom tooltip container and crosshair styles with %s placement',
+		async tooltipPlacement => {
+			const user = userEvent.setup();
+			renderWithTheme( {
+				withTooltipCrosshairs: {
+					showVertical: true,
+					showHorizontal: true,
+					verticalStyle: { stroke: 'purple', strokeWidth: 40, strokeOpacity: 0.12 },
+					horizontalStyle: { stroke: 'orange', strokeDasharray: '4 2' },
+				},
+				tooltipPlacement,
+				tooltipStyle: { backgroundColor: 'black', color: 'white', boxShadow: 'none' },
+			} );
+			screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			const vertical = screen.getByTestId( 'xy-chart-tooltip-crosshair-vertical' );
+			expect( vertical ).toHaveAttribute( 'stroke', 'purple' );
+			expect( vertical ).toHaveAttribute( 'stroke-width', '40' );
+			expect( vertical ).toHaveAttribute( 'stroke-opacity', '0.12' );
+			const horizontal = screen.getByTestId( 'xy-chart-tooltip-crosshair-horizontal' );
+			expect( horizontal ).toHaveAttribute( 'stroke', 'orange' );
+			expect( horizontal ).toHaveAttribute( 'stroke-dasharray', '4 2' );
+			expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( {
+				'background-color': 'rgb(0, 0, 0)',
+				color: 'rgb(255, 255, 255)',
+				'box-shadow': 'none',
+			} );
+			expect( screen.getByTestId( 'line-chart-tooltip-content' ) ).toHaveStyle( {
+				color: 'rgb(255, 255, 255)',
+			} );
+		}
+	);
+	test.each( [
+		[
+			{ color: 'white' },
+			'rgb(255, 255, 255)',
+			'var(--a8c-charts-color-tooltip-surface, rgb(0 0 0 / 85%))',
+			{ color: 'rgb(255, 255, 255)' },
+		],
+		[ { backgroundColor: 'white' }, 'var(--a8c-charts-color-label)', 'rgb(255, 255, 255)', {} ],
+		[ { background: 'white' }, 'var(--a8c-charts-color-label)', 'white', {} ],
+		[
+			{ color: 'white', background: 'black' },
+			'rgb(255, 255, 255)',
+			'black',
+			{ color: 'rgb(255, 255, 255)' },
+		],
+	] )(
+		'applies directional tooltip color defaults: %j',
+		async ( tooltipStyle, color, background, containerColorStyle ) => {
+			const user = userEvent.setup();
+			const defaults = document.createElement( 'style' );
+			defaults.textContent = `.line-chart__tooltip {
+				color: var(--a8c-charts-color-label);
+				background: var(--a8c-charts-color-surface);
+			}`;
+			renderWithTheme( { tooltipStyle } );
+			const chart = screen.getByTestId( 'line-chart' );
+			chart.appendChild( defaults );
+			chart.style.setProperty( '--a8c-charts-color-label', '#000' );
+			chart.style.setProperty( '--a8c-charts-color-label-axis', '#aaa' );
+			chart.style.setProperty( '--a8c-charts-color-surface', '#fff' );
+			screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+			await user.keyboard( '{ArrowRight}' );
+
+			const content = screen.getByTestId( 'line-chart-tooltip-content' );
+			expect( content ).toHaveStyle( {
+				color,
+				[ 'backgroundColor' in tooltipStyle ? 'background-color' : 'background' ]:
+					'background' in tooltipStyle || 'backgroundColor' in tooltipStyle
+						? background
+						: 'var(--a8c-charts-color-surface)',
+			} );
+			const container = screen.getByTestId( 'bounded-tooltip' );
+			expect( container ).toHaveStyle( {
+				...containerColorStyle,
+				[ 'background' in tooltipStyle ? 'background' : 'background-color' ]: background,
+			} );
+		}
+	);
+
+	test( 'preserves the existing tooltip colors for noncolor overrides', async () => {
+		const user = userEvent.setup();
+		renderWithTheme( { tooltipStyle: { boxShadow: 'none' } } );
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		const content = screen.getByTestId( 'line-chart-tooltip-content' );
+		expect( content.style.getPropertyValue( 'color' ) ).toBe( '' );
+		expect( content.style.getPropertyValue( 'background' ) ).toBe( '' );
+		const container = screen.getByTestId( 'bounded-tooltip' );
+		expect( container ).toHaveStyle( { 'box-shadow': 'none' } );
+		expect( container.style.getPropertyValue( 'background' ) ).toBe( '' );
+		expect( container.style.getPropertyValue( 'color' ) ).not.toBe(
+			'var(--a8c-charts-color-label-inverse)'
+		);
+	} );
+
 	describe( 'Data Validation', () => {
 		test( 'handles empty data array', () => {
 			renderWithTheme( { data: [] } );
@@ -445,10 +545,11 @@ describe( 'LineChart', () => {
 				data: [
 					{
 						label: 'Series A',
-						// A day apart: spacing inference would read this as daily buckets.
+						// 23h apart (not 24, and not both midnight): spacing inference would
+						// read this as daily buckets, and the two hours format distinctly.
 						data: [
 							{ date: new Date( '2024-01-01T00:00:00' ), value: 10 },
-							{ date: new Date( '2024-01-02T00:00:00' ), value: 20 },
+							{ date: new Date( '2024-01-01T23:00:00' ), value: 20 },
 						],
 					},
 				],
@@ -458,6 +559,27 @@ describe( 'LineChart', () => {
 			expect( ticks.length ).toBeGreaterThan( 1 );
 		} );
 
+		// Exactly 24 hours apart: bare hours would print "12 AM" twice and leave the
+		// second day unnamed, so the span reads as multi-day and dates its ticks.
+		test( 'names both days when two sub-daily points sit a full day apart', () => {
+			renderWithTheme( {
+				width: 800,
+				options: { axis: { x: { tickResolution: 'hour' } } },
+				data: [
+					{
+						label: 'Series A',
+						data: [
+							{ date: new Date( '2024-01-01T00:00:00' ), value: 10 },
+							{ date: new Date( '2024-01-02T00:00:00' ), value: 20 },
+						],
+					},
+				],
+			} );
+
+			expect( screen.getByText( 'Jan 1' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Jan 2' ) ).toBeInTheDocument();
+		} );
+
 		test( 'renders ticks in short date format.', () => {
 			renderWithTheme( {
 				width: 800,
@@ -599,6 +721,8 @@ describe( 'LineChart', () => {
 			expect( ticks.length ).toBeLessThan( 6 ); // Not much space
 		} );
 
+		// One repeated instant carries no spacing, so the axis falls back to
+		// calendar dates rather than reading a zero gap as hourly buckets.
 		test( 'renders only one tick when all ticks are the same', () => {
 			renderWithTheme( {
 				width: 800,
@@ -614,7 +738,7 @@ describe( 'LineChart', () => {
 				],
 			} );
 
-			const ticks = screen.getAllByText( /\d+ [AP]M/ );
+			const ticks = screen.getAllByText( /^[A-Z][a-z]{2} \d{1,2}$/ );
 			expect( ticks ).toHaveLength( 1 );
 		} );
 	} );
@@ -1201,44 +1325,53 @@ describe( 'LineChart', () => {
 		} );
 
 		describe( 'Arrow Key Navigation', () => {
-			test( 'right arrow key navigates to next data point', async () => {
-				const user = userEvent.setup();
-				renderWithTheme( {
-					data: [
-						{
-							label: 'Series A',
-							data: [
-								{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
-								{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
-							],
-							options: {},
-						},
-						{
-							label: 'Series B',
-							data: [
-								{ date: new Date( '2024-01-01' ), value: 15, label: 'Jan 1' },
-								{ date: new Date( '2024-01-02' ), value: 25, label: 'Jan 2' },
-							],
-							options: {},
-						},
-					],
-				} );
-
-				const chart = screen.getByRole( 'grid', { name: /line chart/i } );
-				chart.focus();
-
-				// Single tab should focus on the first tooltip.
-				await user.keyboard( '{ArrowRight}' );
-				expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
-				expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'Series A' );
-				expect( screen.queryByTestId( 'chart-tooltip-1' ) ).not.toBeInTheDocument();
-
-				// Second tab should focus on the second tooltip.
-				await user.keyboard( '{ArrowRight}' );
-				expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveFocus();
-				expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveTextContent( 'Series B' );
-				expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
-			} );
+			test.each( [ 'auto', 'below-axis' ] as const )(
+				'right arrow key navigates with %s tooltips',
+				async tooltipPlacement => {
+					const user = userEvent.setup();
+					renderWithTheme( {
+						tooltipPlacement,
+						data: [
+							{
+								label: 'Series A',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+								],
+								options: {},
+							},
+							{
+								label: 'Series B',
+								data: [
+									{ date: new Date( '2024-01-01' ), value: 15, label: 'Jan 1' },
+									{ date: new Date( '2024-01-02' ), value: 25, label: 'Jan 2' },
+								],
+								options: {},
+							},
+						],
+					} );
+
+					const chart = screen.getByRole( 'grid', { name: /line chart/i } );
+					chart.focus();
+
+					// Single tab should focus on the first tooltip.
+					await user.keyboard( '{ArrowRight}' );
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveFocus();
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveAttribute( 'role', 'tooltip' );
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveAttribute(
+						'aria-atomic',
+						'true'
+					);
+					expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( 'Series A' );
+					expect( screen.queryByTestId( 'chart-tooltip-1' ) ).not.toBeInTheDocument();
+
+					// Second tab should focus on the second tooltip.
+					await user.keyboard( '{ArrowRight}' );
+					expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveFocus();
+					expect( screen.getByTestId( 'chart-tooltip-1' ) ).toHaveTextContent( 'Series B' );
+					expect( screen.queryByTestId( 'chart-tooltip-0' ) ).not.toBeInTheDocument();
+				}
+			);
 
 			test( 'left arrow key navigates to previous data point', async () => {
 				const user = userEvent.setup();

package/src/charts/line-chart/test/tick-placement.test.tsx

@@ -0,0 +1,84 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import LineChart from '../line-chart';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// Each instant below is one day in Los Angeles and the next in Tokyo.
+const data = [
+	{
+		label: 'Series A',
+		data: Array.from( { length: 8 }, ( _, index ) => ( {
+			date: new Date( new Date( '2026-08-02T15:30:00Z' ).getTime() + index * 86400000 ),
+			value: index,
+		} ) ),
+		options: {},
+	},
+];
+
+// A long series and a short one, so hiding the long one leaves visx a much
+// narrower domain than the whole dataset would give.
+const monthly = ( label: string, count: number ) => ( {
+	label,
+	data: Array.from( { length: count }, ( _, index ) => ( {
+		date: new Date( Date.UTC( 2026, index, 1, 12 ) ),
+		value: index,
+	} ) ),
+	options: {},
+} );
+
+describe( 'line chart tick placement', () => {
+	it( 'places one tick per host zone calendar day, with no gap', () => {
+		render(
+			<GlobalChartsProvider locale="en-US" timeZone="Asia/Tokyo">
+				<LineChart width={ 500 } height={ 300 } withGradientFill={ false } data={ data } />
+			</GlobalChartsProvider>
+		);
+
+		const ticks = screen.getAllByText( /^[A-Z][a-z]{2} \d{1,2}$/ );
+		expect( ticks.map( tick => tick.textContent ) ).toEqual( [
+			'Aug 3',
+			'Aug 4',
+			'Aug 5',
+			'Aug 6',
+			'Aug 7',
+			'Aug 8',
+			'Aug 9',
+			'Aug 10',
+		] );
+	} );
+
+	it( 'keeps every tick inside the axis when a series is hidden', () => {
+		const { container } = render(
+			<GlobalChartsProvider locale="en-US" timeZone="Asia/Tokyo">
+				<LineChart
+					width={ 500 }
+					height={ 300 }
+					withGradientFill={ false }
+					data={ [ monthly( 'Long', 12 ), monthly( 'Short', 3 ) ] }
+					defaultHiddenSeries={ [ 'Long' ] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		// The x axis renders before the y axis, and neither carries an orientation class.
+		/* eslint-disable testing-library/no-container, testing-library/no-node-access -- A tick's position is an SVG attribute no query reaches. */
+		const xAxis = container.querySelectorAll( '.visx-axis' )[ 0 ];
+		const offsets = Array.from( xAxis.querySelectorAll( '.visx-axis-tick text' ) ).map( tick =>
+			Number( tick.getAttribute( 'x' ) )
+		);
+		/* eslint-enable testing-library/no-container, testing-library/no-node-access */
+
+		expect( offsets.length ).toBeGreaterThan( 1 );
+		for ( const offset of offsets ) {
+			expect( offset ).toBeGreaterThanOrEqual( 0 );
+			expect( offset ).toBeLessThanOrEqual( 500 );
+		}
+	} );
+} );

package/src/charts/line-chart/test/tooltip-resolution.test.tsx

@@ -0,0 +1,140 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { GlobalChartsProvider } from '../../../providers';
+import LineChart, { renderDefaultTooltip } from '../line-chart';
+import type { BucketInfo, DataPointDate } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+const paramsFor = ( date: Date ) =>
+	( {
+		tooltipData: {
+			nearestDatum: { key: 'Series A', datum: { date, value: 10 }, index: 0, distance: 0 },
+			datumByKey: { 'Series A': { key: 'Series A', datum: { date, value: 10 }, index: 0 } },
+		},
+	} ) as unknown as RenderTooltipParams< DataPointDate >;
+
+const HOURLY: BucketInfo = { bucket: 'hour', displayResolution: 'hour' };
+const DAILY: BucketInfo = { bucket: 'day', displayResolution: 'day' };
+const MONTHLY: BucketInfo = { bucket: 'month', displayResolution: 'month' };
+const YEARLY: BucketInfo = { bucket: 'year', displayResolution: 'year' };
+
+// 09:30 and 13:30 on the same Tokyo calendar day.
+const morning = new Date( '2026-08-02T00:30:00Z' );
+const afternoon = new Date( '2026-08-02T04:30:00Z' );
+
+const headingFor = ( date: Date, bucketInfo?: BucketInfo, locale = 'en-US' ) => {
+	const { container, unmount } = render(
+		<GlobalChartsProvider locale={ locale } timeZone="Asia/Tokyo">
+			{ renderDefaultTooltip( { ...paramsFor( date ), bucketInfo } ) }
+		</GlobalChartsProvider>
+	);
+	const text = container.textContent ?? '';
+	unmount();
+	return text;
+};
+
+describe( 'default tooltip at hourly resolution', () => {
+	it( 'distinguishes two hours of the same day', () => {
+		expect( headingFor( morning, HOURLY ) ).not.toBe( headingFor( afternoon, HOURLY ) );
+	} );
+
+	it( 'names the hour in the host time zone', () => {
+		// Full de-DE/Asia/Tokyo heading: pins the date style and the hour together.
+		expect( headingFor( morning, HOURLY, 'de-DE' ) ).toContain( '2.8.2026, 09 Uhr' );
+	} );
+
+	it( 'keeps the day in the heading at month and year resolution', () => {
+		expect( headingFor( morning, MONTHLY, 'de-DE' ) ).toContain( '2.8.2026' );
+		expect( headingFor( morning, YEARLY, 'de-DE' ) ).toContain( '2.8.2026' );
+	} );
+
+	it( 'names no hour at daily resolution', () => {
+		expect( headingFor( morning, DAILY ) ).not.toContain( 'AM' );
+	} );
+
+	it( 'renders as a date when no bucketInfo is supplied', () => {
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				{ renderDefaultTooltip( paramsFor( new Date( '2026-08-02T15:30:00Z' ) ) ) }
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( '3.8.2026' ) ).toBeInTheDocument();
+	} );
+
+	it( 'reaches the tooltip an hourly chart opens', async () => {
+		const user = userEvent.setup();
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<LineChart
+					width={ 500 }
+					height={ 300 }
+					withGradientFill={ false }
+					options={ { axis: { x: { tickResolution: 'hour' } } } }
+					data={ [
+						{
+							label: 'Series A',
+							data: [
+								{ date: morning, value: 10 },
+								{ date: afternoon, value: 20 },
+							],
+							options: {},
+						},
+					] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( '2.8.2026, 09 Uhr' );
+	} );
+
+	it( 'drops the hour once the hourly series is hidden, as the axis does', async () => {
+		const user = userEvent.setup();
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<LineChart
+					width={ 500 }
+					height={ 300 }
+					withGradientFill={ false }
+					defaultHiddenSeries={ [ 'Hourly' ] }
+					data={ [
+						{
+							label: 'Hourly',
+							data: [
+								{ date: morning, value: 10 },
+								{ date: afternoon, value: 20 },
+							],
+							options: {},
+						},
+						{
+							label: 'Daily',
+							data: [
+								{ date: morning, value: 5 },
+								{ date: new Date( '2026-08-03T00:30:00Z' ), value: 6 },
+							],
+							options: {},
+						},
+					] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		screen.getByRole( 'grid', { name: /line chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		const tooltip = screen.getByTestId( 'chart-tooltip-0' );
+		expect( tooltip ).toHaveTextContent( '2.8.2026' );
+		expect( tooltip ).not.toHaveTextContent( 'Uhr' );
+	} );
+} );