@automattic/charts 3.2.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "3.2.0",
+	"version": "4.1.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -65,6 +65,7 @@
 	"dependencies": {
 		"@automattic/number-formatters": "^1.2.8",
 		"@babel/runtime": "7.29.7",
+		"@date-fns/tz": "1.4.1",
 		"@react-spring/web": "10.1.1",
 		"@visx/annotation": "^4.0.0",
 		"@visx/axis": "^4.0.0",
@@ -84,8 +85,8 @@
 		"@visx/xychart": "^4.0.0",
 		"@wordpress/i18n": "^6.0.0",
 		"@wordpress/icons": "^15.0.0",
-		"@wordpress/theme": "1.2.0",
-		"@wordpress/ui": "0.20.0",
+		"@wordpress/theme": "2.1.1-next.v.202608281122.0",
+		"@wordpress/ui": "0.21.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",
@@ -110,9 +111,9 @@
 		"@types/react-dom": "18.3.7",
 		"@typescript/native-preview": "7.0.0-dev.20260707.2",
 		"@visx/glyph": "4.0.0",
-		"@wordpress/components": "37.0.0",
-		"@wordpress/element": "8.3.0",
-		"@wordpress/private-apis": "1.53.0",
+		"@wordpress/components": "40.0.0",
+		"@wordpress/element": "8.6.0",
+		"@wordpress/private-apis": "1.54.0",
 		"babel-jest": "30.4.1",
 		"identity-obj-proxy": "^3.0.0",
 		"jest": "30.4.2",

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

@@ -22,21 +22,24 @@ import {
 import {
 	GlobalChartsProvider,
 	GlobalChartsContext,
+	useChartFormatting,
 	useChartId,
 	useChartRegistration,
 	useGlobalChartsContext,
-	useGlobalChartsTheme,
 } from '../../providers';
 import { useDefaultHiddenSeries } from '../../providers/chart-context/hooks/use-default-hidden-series';
 import { attachSubComponents } from '../../utils';
+import { getBucketInfo } from '../../utils/bucket-info';
 import { renderDefaultTooltip } from '../line-chart';
 import { useChartChildren } from '../private/chart-composition';
 import { ChartInstanceContext, type ChartInstanceRef } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
-import { getCurveType, getFormatter, guessOptimalNumTicks } from '../private/time-axis';
+import { getCurveType } from '../private/time-axis';
+import { buildTimeAxisOptions } from '../private/time-axis-options';
 import { withResponsive } from '../private/with-responsive';
 import { useXZoom, ZoomResetButton, ZoomSelectionRect, ZoomClip } from '../private/x-zoom';
+import plotStyles from '../private/xy-plot/xy-plot.module.scss';
 import styles from './area-chart.module.scss';
 import { AreaChartScalesRef, HoverGlyphs, validateData } from './private';
 import type { AreaChartProps } from './types';
@@ -71,8 +74,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 			onPointerMove,
 			onPointerOut,
 			zoomable = false,
-			rescaleYOnVisibilityChange,
-			rescaleYOnLegendToggle,
+			rescaleYOnVisibilityChange = true,
 			defaultHiddenSeries,
 			children,
 			gridVisibility,
@@ -84,10 +86,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 		const legendShape = legend.shape ?? 'rect';
 		const legendPosition = legend.position ?? 'bottom';
 
-		// New prop wins; fall back to the deprecated `rescaleYOnLegendToggle`; default to rescaling.
-		const rescaleYOnVisibility = rescaleYOnVisibilityChange ?? rescaleYOnLegendToggle ?? true;
-
-		const providerTheme = useGlobalChartsTheme();
+		const formatting = useChartFormatting();
 		const theme = useXYChartTheme( data );
 		const chartId = useChartId( providedChartId );
 		const hiddenSeries = useDefaultHiddenSeries( chartId, defaultHiddenSeries );
@@ -160,7 +159,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 		// around zero); letting visx derive the domain is correct there.
 		const fixedYDomain = useMemo< [ number, number ] | undefined >( () => {
 			if (
-				rescaleYOnVisibility ||
+				rescaleYOnVisibilityChange ||
 				! dataSorted.length ||
 				! dataSorted[ 0 ].data.length ||
 				( stacked && stackOffset !== 'none' )
@@ -202,21 +201,21 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 			}
 			if ( max === -Infinity ) return undefined;
 			return [ Math.min( 0, min ), max ];
-		}, [ dataSorted, stacked, stackOffset, rescaleYOnVisibility ] );
+		}, [ dataSorted, stacked, stackOffset, rescaleYOnVisibilityChange ] );
 
 		const chartOptions = useMemo( () => {
-			const { tickResolution, tickFormat, ...xAxisOptions } = options?.axis?.x ?? {};
-			const formatter = tickFormat || getFormatter( dataSorted, tickResolution );
-
 			return {
 				axis: {
-					x: {
-						orientation: 'bottom' as const,
-						numTicks: guessOptimalNumTicks( dataSorted, width, formatter ),
-						tickFormat: formatter,
-						display: true,
-						...xAxisOptions,
-					},
+					x: buildTimeAxisOptions( {
+						dataSorted,
+						width,
+						axisOptions: options?.axis?.x,
+						scaleDomain: options?.xScale?.domain,
+						zoomDomain: zoom.domain,
+						formatting,
+						// No `isSeriesRendered`: a hidden area stays mounted with a zeroed
+						// yAccessor, so it still contributes to the x domain.
+					} ),
 					y: {
 						orientation: 'left' as const,
 						numTicks: 4,
@@ -239,7 +238,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, stacked, fixedYDomain, zoom.domain ] );
+		}, [ options, dataSorted, width, stacked, fixedYDomain, zoom.domain, formatting ] );
 
 		const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme );
 
@@ -284,10 +283,24 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 			() => new Set( seriesWithVisibility.filter( s => s.isVisible ).map( s => s.series.label ) ),
 			[ seriesWithVisibility ]
 		);
+
+		// Classified from the visible series, not the axis's: a hidden area stays in
+		// the x domain for its animation, but the tooltip below drops its data, so a
+		// heading naming that series' bucket would name one no visible datum has.
+		const bucketInfo = useMemo(
+			() =>
+				getBucketInfo(
+					dataSorted.filter( series => visibleLabels.has( series.label ) ),
+					options?.axis?.x?.tickResolution
+				),
+			[ dataSorted, visibleLabels, options?.axis?.x?.tickResolution ]
+		);
 		const filteredRenderTooltip = useCallback(
 			( params: Parameters< typeof renderTooltip >[ 0 ] ) => {
 				const datumByKey = params?.tooltipData?.datumByKey;
-				if ( ! datumByKey ) return renderTooltip( params );
+				if ( ! datumByKey ) {
+					return renderTooltip( { ...params, bucketInfo } );
+				}
 				const filtered = Object.fromEntries(
 					Object.entries( datumByKey ).filter( ( [ key ] ) => visibleLabels.has( key ) )
 				);
@@ -302,6 +315,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 						: { ...Object.values( filtered )[ 0 ], distance: nearestDatum?.distance ?? 0 };
 				return renderTooltip( {
 					...params,
+					bucketInfo,
 					tooltipData: {
 						...params.tooltipData,
 						datumByKey: filtered,
@@ -309,7 +323,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 					} as typeof params.tooltipData,
 				} );
 			},
-			[ renderTooltip, visibleLabels ]
+			[ renderTooltip, visibleLabels, bucketInfo ]
 		);
 
 		// Defaults that depend on stacked vs overlapping mode.
@@ -405,7 +419,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 								onBlur={ onChartBlur }
 							>
 								{ chartHeight > 0 && (
-									<div ref={ chartRef } style={ { position: 'relative' } }>
+									<div ref={ chartRef } className={ plotStyles[ 'xy-plot' ] }>
 										{ zoomable && zoom.domain && <ZoomResetButton onClick={ zoom.reset } /> }
 										<XYChart
 											theme={ theme }
@@ -483,7 +497,7 @@ const AreaChartInternal = forwardRef< ChartInstanceRef, AreaChartProps >(
 														stackOffset={ stackOffset }
 														getElementStyles={ getElementStyles }
 														// useXYChartTheme resolved this role inside its memo, against the chart's scope element; reading it back avoids a getComputedStyle on every render.
-														strokeColor={ theme.backgroundColor ?? providerTheme.backgroundColor }
+														strokeColor={ theme.backgroundColor }
 													/>
 												</>
 											) }

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

@@ -317,7 +317,7 @@ describe( 'AreaChart', () => {
 			expect( afterToggleDomain![ 1 ] ).toBeLessThan( initialDomain![ 1 ] );
 		} );
 
-		test( 'y-axis stays pinned for unstacked area when rescaleYOnLegendToggle is false', async () => {
+		test( 'y-axis stays pinned for unstacked area when rescaleYOnVisibilityChange is false', async () => {
 			// Exercises the non-stacked branch of fixedYDomain, which scans the
 			// raw min/max across all series rather than summing stack columns.
 			const user = userEvent.setup();
@@ -330,7 +330,7 @@ describe( 'AreaChart', () => {
 						chartId="test-interactive-domain-pin-unstacked"
 						legend={ { interactive: true } }
 						stacked={ false }
-						rescaleYOnLegendToggle={ false }
+						rescaleYOnVisibilityChange={ false }
 						ref={ ref }
 					/>
 				</GlobalChartsProvider>
@@ -351,35 +351,6 @@ describe( 'AreaChart', () => {
 			expect( afterToggleDomain ).toEqual( initialDomain );
 		} );
 
-		test( 'y-axis stays pinned when rescaleYOnLegendToggle is false', async () => {
-			const user = userEvent.setup();
-			const ref = createRef< ChartInstanceRef >();
-			render(
-				<GlobalChartsProvider>
-					<AreaChartUnresponsive
-						{ ...defaultProps }
-						showLegend
-						chartId="test-interactive-domain-pin"
-						legend={ { interactive: true } }
-						rescaleYOnLegendToggle={ false }
-						ref={ ref }
-					/>
-				</GlobalChartsProvider>
-			);
-
-			const initialDomain = (
-				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
-			 )?.domain();
-			expect( initialDomain ).toBeDefined();
-
-			await user.click( screen.getByText( 'Series A' ) );
-
-			const afterToggleDomain = (
-				ref.current?.getScales()?.yScale as { domain: () => number[] } | undefined
-			 )?.domain();
-			expect( afterToggleDomain ).toEqual( initialDomain );
-		} );
-
 		test( 'y-axis stays pinned when rescaleYOnVisibilityChange is false', async () => {
 			const user = userEvent.setup();
 			const ref = createRef< ChartInstanceRef >();
@@ -388,7 +359,7 @@ describe( 'AreaChart', () => {
 					<AreaChartUnresponsive
 						{ ...defaultProps }
 						showLegend
-						chartId="test-interactive-domain-pin-new"
+						chartId="test-interactive-domain-pin"
 						legend={ { interactive: true } }
 						rescaleYOnVisibilityChange={ false }
 						ref={ ref }
@@ -607,7 +578,7 @@ describe( 'AreaChart', () => {
 						chartId="test-interactive-negative"
 						showLegend
 						legend={ { interactive: true } }
-						rescaleYOnLegendToggle={ false }
+						rescaleYOnVisibilityChange={ false }
 						data={ [
 							{
 								label: 'Pos',

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

@@ -0,0 +1,55 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import AreaChart from '../area-chart';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+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: {},
+} );
+
+const xAxisTickOffsets = ( container: HTMLElement ) => {
+	/* eslint-disable testing-library/no-node-access -- A tick's position is an SVG attribute no query reaches. */
+	const xAxis = container.querySelectorAll( '.visx-axis' )[ 0 ];
+	return Array.from( xAxis.querySelectorAll( '.visx-axis-tick text' ) ).map( tick =>
+		Number( tick.getAttribute( 'x' ) )
+	);
+	/* eslint-enable testing-library/no-node-access */
+};
+
+const renderChart = ( defaultHiddenSeries?: string[] ) =>
+	render(
+		<GlobalChartsProvider locale="en-US" timeZone="Asia/Tokyo">
+			<AreaChart
+				width={ 500 }
+				height={ 300 }
+				data={ [ monthly( 'Long', 12 ), monthly( 'Short', 3 ) ] }
+				defaultHiddenSeries={ defaultHiddenSeries }
+			/>
+		</GlobalChartsProvider>
+	);
+
+describe( 'area chart tick placement', () => {
+	it( 'keeps ticks spanning the full domain when a series is hidden', () => {
+		const shown = xAxisTickOffsets( renderChart().container );
+		const hidden = xAxisTickOffsets( renderChart( [ 'Long' ] ).container );
+
+		expect( hidden ).toEqual( shown );
+		expect( hidden.length ).toBeGreaterThan( 1 );
+		for ( const offset of hidden ) {
+			expect( offset ).toBeGreaterThanOrEqual( 0 );
+			expect( offset ).toBeLessThanOrEqual( 500 );
+		}
+	} );
+} );

package/src/charts/area-chart/test/tooltip-resolution-branches.test.tsx

@@ -0,0 +1,86 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import AreaChart from '../area-chart';
+import type { DataPointDate } from '../../../types';
+import type { RenderTooltipParams } from '../../../visx/types';
+import type { ReactNode } from 'react';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// Captures AreaChart's `filteredRenderTooltip` so its early-return branch can be
+// called directly: visx always sets `datumByKey` when it opens a tooltip.
+type CapturedRenderTooltip = ( params: RenderTooltipParams< DataPointDate > ) => ReactNode;
+let capturedRenderTooltip: CapturedRenderTooltip | undefined;
+jest.mock( '../../../components/tooltip', () => ( {
+	...jest.requireActual( '../../../components/tooltip' ),
+	AccessibleTooltip: ( props: { renderTooltip?: CapturedRenderTooltip } ) => {
+		capturedRenderTooltip = props.renderTooltip;
+		return null;
+	},
+} ) );
+
+// 09:30 on the Tokyo calendar day.
+const morning = new Date( '2026-08-02T00:30:00Z' );
+
+const datumA = { key: 'Series A', datum: { date: morning, value: 10 } as DataPointDate, index: 0 };
+const datumB = { key: 'Series B', datum: { date: morning, value: 5 } as DataPointDate, index: 0 };
+
+// Full de-DE/Asia/Tokyo heading for `morning`: pins the date style and the hour together.
+const EXPECTED_HEADING = '2.8.2026, 09 Uhr';
+
+const renderHourlyChart = ( defaultHiddenSeries?: string[] ) =>
+	render(
+		<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+			<AreaChart
+				width={ 500 }
+				height={ 300 }
+				options={ { axis: { x: { tickResolution: 'hour' } } } }
+				defaultHiddenSeries={ defaultHiddenSeries }
+				data={ [
+					{ label: 'Series A', data: [ datumA.datum ], options: {} },
+					{ label: 'Series B', data: [ datumB.datum ], options: {} },
+				] }
+			/>
+		</GlobalChartsProvider>
+	);
+
+const renderCaptured = ( params: RenderTooltipParams< DataPointDate > ) =>
+	render(
+		<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+			<div data-testid="captured-tooltip">{ capturedRenderTooltip!( params ) }</div>
+		</GlobalChartsProvider>
+	);
+
+describe( "AreaChart's filteredRenderTooltip", () => {
+	beforeEach( () => {
+		capturedRenderTooltip = undefined;
+	} );
+
+	it( 'names the hour on the early-return path, before datumByKey exists', () => {
+		renderHourlyChart();
+
+		const params = {
+			tooltipData: { nearestDatum: datumA, datumByKey: undefined },
+		} as unknown as RenderTooltipParams< DataPointDate >;
+		renderCaptured( params );
+
+		expect( screen.getByTestId( 'captured-tooltip' ) ).toHaveTextContent( EXPECTED_HEADING );
+	} );
+
+	it( 'names the hour on the filtered path, with a hidden series', () => {
+		renderHourlyChart( [ 'Series B' ] );
+
+		const params = {
+			tooltipData: { nearestDatum: datumA, datumByKey: { 'Series A': datumA, 'Series B': datumB } },
+		} as unknown as RenderTooltipParams< DataPointDate >;
+		renderCaptured( params );
+
+		expect( screen.getByTestId( 'captured-tooltip' ) ).toHaveTextContent( EXPECTED_HEADING );
+	} );
+} );

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

@@ -0,0 +1,69 @@
+/**
+ * @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 AreaChart from '../area-chart';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// 09:30 on the Tokyo calendar day.
+const morning = new Date( '2026-08-02T00:30:00Z' );
+
+describe( 'area chart tooltip bucket info', () => {
+	it( 'names the hour on a mounted chart', async () => {
+		const user = userEvent.setup();
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<AreaChart
+					width={ 500 }
+					height={ 300 }
+					options={ { axis: { x: { tickResolution: 'hour' } } } }
+					data={ [ { label: 'Series A', data: [ { date: morning, value: 10 } ], options: {} } ] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		screen.getByRole( 'grid', { name: /area chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'chart-tooltip-0' ) ).toHaveTextContent( '2.8.2026, 09 Uhr' );
+	} );
+
+	// The axis keeps a hidden area in its domain for the animation, but the
+	// tooltip drops its data, so the bucket has to follow the tooltip.
+	it( 'ignores a hidden series when naming the bucket', async () => {
+		const user = userEvent.setup();
+		const hourly = Array.from( { length: 4 }, ( _, index ) => ( {
+			date: new Date( Date.UTC( 2026, 7, 2, index ) ),
+			value: index,
+		} ) );
+		const daily = Array.from( { length: 3 }, ( _, index ) => ( {
+			date: new Date( Date.UTC( 2026, 7, 2 + index ) ),
+			value: index,
+		} ) );
+
+		render(
+			<GlobalChartsProvider locale="de-DE" timeZone="Asia/Tokyo">
+				<AreaChart
+					width={ 500 }
+					height={ 300 }
+					defaultHiddenSeries={ [ 'Hourly' ] }
+					data={ [
+						{ label: 'Hourly', data: hourly, options: {} },
+						{ label: 'Daily', data: daily, options: {} },
+					] }
+				/>
+			</GlobalChartsProvider>
+		);
+
+		screen.getByRole( 'grid', { name: /area chart/i } ).focus();
+		await user.keyboard( '{ArrowRight}' );
+
+		expect( screen.getByTestId( 'chart-tooltip-0' ) ).not.toHaveTextContent( 'Uhr' );
+	} );
+} );

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

@@ -1,5 +1,6 @@
 import type {
 	BaseChartProps,
+	BucketInfo,
 	DataPointDate,
 	SeriesData,
 	SeriesChartLegendConfig,
@@ -39,7 +40,9 @@ export interface AreaChartProps extends BaseChartProps< SeriesData[] >, SeriesVi
 	/**
 	 * Custom tooltip renderer.
 	 */
-	renderTooltip?: ( params: RenderTooltipParams< DataPointDate > ) => ReactNode;
+	renderTooltip?: (
+		params: RenderTooltipParams< DataPointDate > & { bucketInfo?: BucketInfo }
+	) => ReactNode;
 	/**
 	 * Whether to show crosshair lines in the tooltip.
 	 */
@@ -71,11 +74,5 @@ export interface AreaChartProps extends BaseChartProps< SeriesData[] >, SeriesVi
 	 * @default true
 	 */
 	rescaleYOnVisibilityChange?: boolean;
-	/**
-	 * @deprecated Use `rescaleYOnVisibilityChange`. The behaviour keys off series
-	 * visibility changing, not specifically a legend toggle. Still honoured when
-	 * `rescaleYOnVisibilityChange` is not set.
-	 */
-	rescaleYOnLegendToggle?: boolean;
 	children?: ReactNode;
 }

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

@@ -27,6 +27,7 @@ import { ChartInstanceContext } from '../private/chart-instance-context';
 import { ChartLayout } from '../private/chart-layout';
 import { getAllHiddenMessage, SvgEmptyState } from '../private/svg-empty-state';
 import { withResponsive } from '../private/with-responsive';
+import plotStyles from '../private/xy-plot/xy-plot.module.scss';
 import styles from './bar-chart.module.scss';
 import {
 	useBarChartOptions,
@@ -587,7 +588,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 							onBlur={ onChartBlur }
 						>
 							{ chartHeight > 0 && (
-								<div ref={ chartRef }>
+								<div ref={ chartRef } className={ plotStyles[ 'xy-plot' ] }>
 									<XYChart
 										theme={ theme }
 										width={ width }

package/src/charts/bar-chart/private/test/use-bar-chart-options-formatting.test.tsx

@@ -0,0 +1,69 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { renderHook } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../../providers';
+import { useBarChartOptions } from '../use-bar-chart-options';
+import type { SeriesData } from '../../../../types';
+import type { ReactNode } from 'react';
+
+// The runtime locale stays en-US: a bucket labeled in German, on Tokyo's
+// calendar day, can only come from the provider.
+
+// 15:30 UTC is Aug 2 in Los Angeles and Aug 3 in Tokyo.
+const START = new Date( '2026-08-02T15:30:00Z' );
+
+const daily: SeriesData[] = [
+	{
+		label: 'Series A',
+		data: Array.from( { length: 14 }, ( _, i ) => ( {
+			date: new Date( START.getTime() + i * 24 * 60 * 60 * 1000 ),
+			value: 10 + i,
+		} ) ),
+		options: {},
+	},
+];
+
+const withProvider =
+	( props: { locale?: string; timeZone?: string } = {} ) =>
+	( { children }: { children: ReactNode } ) => (
+		<GlobalChartsProvider { ...props }>{ children }</GlobalChartsProvider>
+	);
+
+const optionsFor = (
+	props?: { locale?: string; timeZone?: string },
+	options?: Parameters< typeof useBarChartOptions >[ 2 ]
+) =>
+	renderHook( () => useBarChartOptions( daily, false, options ), {
+		wrapper: withProvider( props ),
+	} ).result.current;
+
+describe( 'useBarChartOptions with a host formatting context', () => {
+	it( 'labels the tooltip bucket in the provider locale and time zone', () => {
+		const { tooltip } = optionsFor( { locale: 'de-DE', timeZone: 'Asia/Tokyo' } );
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( '3. August 2026' );
+	} );
+
+	it( 'labels a weekly bucket in the provider locale and time zone', () => {
+		const { tooltip } = optionsFor(
+			{ locale: 'de-DE', timeZone: 'Asia/Tokyo' },
+			{ axis: { x: { tickResolution: 'week' } } }
+		);
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( 'Week of 3. August 2026' );
+	} );
+
+	it( 'labels the axis ticks in the provider locale and time zone', () => {
+		const { axis } = optionsFor( { locale: 'de-DE', timeZone: 'Asia/Tokyo' } );
+
+		expect( axis.x.tickFormat( START, 0, [] ) ).toBe( '3. Aug.' );
+	} );
+
+	it( 'falls back to the runtime locale and zone when the provider supplies none', () => {
+		const { tooltip, axis } = optionsFor();
+
+		expect( tooltip.labelFormatter( START.getTime(), 0, [] ) ).toBe( 'August 2, 2026' );
+		expect( axis.x.tickFormat( START, 0, [] ) ).toBe( 'Aug 2' );
+	} );
+} );