@automattic/charts 3.2.0 → 4.0.0

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

@@ -1,11 +1,12 @@
 import { Group } from '@visx/group';
 import { Pie } from '@visx/shape';
 import { Text } from '@visx/text';
-import { useTooltip, useTooltipInPortal } from '@visx/tooltip';
+import { useTooltip } from '@visx/tooltip';
 import clsx from 'clsx';
-import { useCallback, useContext, useMemo } from 'react';
+import { useCallback, useContext, useMemo, useRef } from 'react';
 import { Legend, useChartLegendItems } from '../../components/legend';
 import { BaseTooltip } from '../../components/tooltip';
+import { BoundedTooltip } from '../../components/tooltip/private/bounded-tooltip';
 import {
 	useDataWithPercentages,
 	useLegendVisibilityData,
@@ -18,7 +19,7 @@ import {
 	useGlobalChartsContext,
 	GlobalChartsContext,
 } from '../../providers';
-import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
+import { useStandaloneScopeClass } from '../../providers/chart-scope';
 import { attachSubComponents } from '../../utils';
 import { Center } from '../private/center';
 import { ChartSVG, ChartHTML, useChartChildren } from '../private/chart-composition';
@@ -189,42 +190,25 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 	const chartId = useChartId( providedChartId );
 	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
 		useTooltip< DataPointPercentageCalculated >();
+	const standaloneScopeClass = useStandaloneScopeClass();
 
-	// Set up portal tooltip for better z-index handling
-	// We get containerBounds to cancel out stale offsets in the position calculation
-	const { containerRef, TooltipInPortal, containerBounds } = useTooltipInPortal( {
-		detectBounds: true,
-		scroll: true,
-		debounce: 0,
-	} );
+	// The tooltip renders inside this element, so pointer coordinates are taken relative to it.
+	const containerRef = useRef< HTMLDivElement >( null );
 
 	const handleMouseMove = useCallback(
 		( event: MouseEvent< SVGElement >, arc: ArcData ) => {
-			// Don't show tooltip until container bounds are measured
-			if ( containerBounds.width === 0 || containerBounds.height === 0 ) {
+			const bounds = containerRef.current?.getBoundingClientRect();
+			if ( ! bounds ) {
 				return;
 			}
 
-			// Use clientX/Y and subtract containerBounds to cancel out any stale offset.
-			// TooltipInPortal calculates: tooltipLeft + containerBounds.left + scrollX
-			// By passing (clientX - containerBounds.left), we get:
-			// (clientX - containerBounds.left) + containerBounds.left + scrollX = clientX + scrollX
-			// This gives correct page coordinates regardless of stale bounds.
 			showTooltip( {
 				tooltipData: arc.data,
-				tooltipLeft: event.clientX - containerBounds.left + tooltipOffsetX,
-				tooltipTop: event.clientY - containerBounds.top + tooltipOffsetY,
+				tooltipLeft: event.clientX - bounds.left + tooltipOffsetX,
+				tooltipTop: event.clientY - bounds.top + tooltipOffsetY,
 			} );
 		},
-		[
-			containerBounds.width,
-			containerBounds.height,
-			containerBounds.left,
-			containerBounds.top,
-			showTooltip,
-			tooltipOffsetX,
-			tooltipOffsetY,
-		]
+		[ showTooltip, tooltipOffsetX, tooltipOffsetY ]
 	);
 
 	const handleMouseLeave = useCallback( () => {
@@ -311,7 +295,9 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 		const errorHeight = errorWidth / 2;
 
 		return (
-			<div className={ styles[ 'pie-semi-circle-chart' ] }>
+			<div
+				className={ clsx( 'pie-semi-circle-chart', styles[ 'pie-semi-circle-chart' ], className ) }
+			>
 				<svg width={ errorWidth } height={ errorHeight } data-testid="pie-chart-svg">
 					<text x="50%" y="50%" textAnchor="middle" className={ styles.error }>
 						{ message }
@@ -372,13 +358,6 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 				data-testid="pie-chart-container"
 				trailingContent={
 					<>
-						{ withTooltips && tooltipOpen && tooltipData && (
-							<TooltipInPortal top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
-								<div className={ CHART_SCOPE_CLASS } role="tooltip">
-									{ renderTooltip( { tooltipData } ) }
-								</div>
-							</TooltipInPortal>
-						) }
 						{ htmlChildren }
 						{ otherChildren }
 					</>
@@ -398,7 +377,7 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 					const innerRadius = radius * ( 1 - thickness );
 
 					return (
-						<Center ref={ containerRef }>
+						<Center ref={ containerRef } className={ styles[ 'pie-semi-circle-chart__plot' ] }>
 							<svg
 								width={ width }
 								height={ height }
@@ -484,6 +463,13 @@ const PieSemiCircleChartInternal: FC< PieSemiCircleChartProps > = ( {
 									) }
 								</Group>
 							</svg>
+							{ withTooltips && tooltipOpen && tooltipData && (
+								<BoundedTooltip top={ tooltipTop || 0 } left={ tooltipLeft || 0 }>
+									<div className={ standaloneScopeClass } role="tooltip">
+										{ renderTooltip( { tooltipData } ) }
+									</div>
+								</BoundedTooltip>
+							) }
 						</Center>
 					);
 				} }

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

@@ -362,3 +362,53 @@ describe( 'PieSemiCircleChart', () => {
 		} );
 	} );
 } );
+
+// Chart container at (100, 50); the tooltip box measures 120x40. Everything
+// else the charts measure (wrapper, clipping lookups) reports the container.
+const mockRects = () =>
+	jest.spyOn( Element.prototype, 'getBoundingClientRect' ).mockImplementation( function (
+		this: Element
+	) {
+		const box = this.classList.contains( 'visx-tooltip' );
+		return {
+			left: box ? 0 : 100,
+			top: box ? 0 : 50,
+			width: box ? 120 : 400,
+			height: box ? 40 : 300,
+			right: box ? 120 : 500,
+			bottom: box ? 40 : 350,
+			x: box ? 0 : 100,
+			y: box ? 0 : 50,
+			toJSON: () => ( {} ),
+		} as DOMRect;
+	} );
+
+describe( 'PieSemiCircleChart tooltip position', () => {
+	afterEach( () => {
+		jest.restoreAllMocks();
+	} );
+
+	it( 'places the box relative to the chart container, at the pointer plus the offsets', async () => {
+		mockRects();
+		const user = userEvent.setup();
+		renderPieChart( {
+			data: [
+				{ label: 'A', value: 60, valueDisplay: '60' },
+				{ label: 'B', value: 40, valueDisplay: '40' },
+			],
+			withTooltips: true,
+			width: 400,
+		} );
+
+		await user.pointer( {
+			target: screen.getAllByTestId( 'pie-segment' )[ 0 ],
+			coords: { clientX: 150, clientY: 120 },
+		} );
+
+		// (150, 120) is (50, 70) inside the container; the default -15px vertical
+		// offset makes that (50, 55), and the box adds 10px each way.
+		expect( screen.getByTestId( 'bounded-tooltip' ) ).toHaveStyle( {
+			transform: 'translate(60px, 65px)',
+		} );
+	} );
+} );

package/src/charts/private/chart-layout/chart-layout.module.scss

@@ -8,8 +8,9 @@
 	// The svg displaying inline includes a few px for descenders, which
 	// confuses some browser environments (e.g. headless Chrome) into
 	// constantly growing the container. Setting it to display as block avoids
-	// that.
-	svg {
+	// that. The tooltip renders in here too, and an inline icon in its rows
+	// must stay inline.
+	svg:not(:global(.visx-tooltip) svg) {
 		display: block;
 	}
 }

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);
+	font-size: var(--wpds-typography-font-size-md);
 	color: var(--a8c-charts-color-label-secondary);
 }

package/src/charts/private/test/axis-formatting.test.tsx

@@ -0,0 +1,85 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../../providers';
+import AreaChart from '../../area-chart/area-chart';
+import BarChart from '../../bar-chart/bar-chart';
+import LineChart from '../../line-chart/line-chart';
+import type { ReactNode } from 'react';
+
+const mockRefCallback = jest.fn();
+jest.mock( '../../../hooks/use-element-size', () => ( {
+	useElementSize: () => [ mockRefCallback, 500, 300 ],
+} ) );
+
+// 15:30 UTC is Aug 2 in the runtime zone and Aug 3 in Tokyo.
+const START = Date.parse( '2026-08-02T15:30:00Z' );
+
+const data = [
+	{
+		label: 'Series A',
+		data: Array.from( { length: 14 }, ( _, i ) => ( {
+			date: new Date( START + i * 24 * 60 * 60 * 1000 ),
+			value: 10 + i,
+		} ) ),
+		options: {},
+	},
+];
+
+const size = { width: 500, height: 300 };
+
+// Every axis labels the data's own buckets, so the fallback names the first
+// point's runtime-zone day rather than a round-numbered instant near it.
+const RUNTIME_TICK = 'Aug 2';
+
+const charts: [ string, ReactNode ][] = [
+	[ 'AreaChart', <AreaChart key="a" { ...size } data={ data } /> ],
+	[ 'BarChart', <BarChart key="b" { ...size } data={ data } /> ],
+	[ 'LineChart', <LineChart key="l" { ...size } data={ data } withGradientFill={ false } /> ],
+];
+
+describe.each( charts )( '%s x axis', ( _name, chart ) => {
+	const renderIn = ( props: { locale?: string; timeZone?: string } ) =>
+		render( <GlobalChartsProvider { ...props }>{ chart }</GlobalChartsProvider> );
+
+	it( "labels ticks in the provider's locale", () => {
+		renderIn( { locale: 'de-DE', timeZone: 'Asia/Tokyo' } );
+
+		expect( screen.getByText( '3. Aug.' ) ).toBeInTheDocument();
+	} );
+
+	it( 'falls back to the runtime locale and zone when the provider supplies none', () => {
+		renderIn( {} );
+
+		expect( screen.getByText( RUNTIME_TICK ) ).toBeInTheDocument();
+	} );
+
+	it( 'relabels when the provider swaps time zone', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider timeZone="Asia/Tokyo">{ chart }</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( 'Aug 3' ) ).toBeInTheDocument();
+
+		rerender( <GlobalChartsProvider timeZone="Pacific/Honolulu">{ chart }</GlobalChartsProvider> );
+
+		expect( screen.getByText( 'Aug 2' ) ).toBeInTheDocument();
+	} );
+} );
+
+// The values WordPress hands out: `get_locale()` is `en_US`, and `timezone_string`
+// is empty on a site set to a raw UTC offset. Unsanitized, `Intl` throws during
+// render and React unmounts the host tree rather than one chart.
+describe( 'a host locale and zone Intl cannot use', () => {
+	it( 'still renders, in the runtime zone, and warns', () => {
+		render(
+			<GlobalChartsProvider locale="en_US" timeZone="">
+				<BarChart { ...size } data={ data } />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByText( 'Aug 2' ) ).toBeInTheDocument();
+		expect( console ).toHaveWarned();
+	} );
+} );

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

@@ -0,0 +1,109 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { getBandTickValues, getFormatter } from '../time-axis';
+import type { useChartDataTransform } from '../../../hooks';
+
+type SortedData = ReturnType< typeof useChartDataTransform >;
+
+const toSeries = ( dates: Date[] ): SortedData =>
+	[
+		{
+			label: 'series',
+			data: dates.map( date => ( { date, value: 1 } ) ),
+		},
+	] as unknown as SortedData;
+
+// Tokyo has no DST, so its midnight is a fixed nine hours before UTC midnight.
+const tokyoMidnight = ( year: number, month: number, day = 1 ) =>
+	new Date( Date.UTC( year, month, day ) - 9 * 60 * 60 * 1000 );
+
+const every = ( start: Date, count: number, hours: number ): Date[] =>
+	Array.from(
+		{ length: count },
+		( _, i ) => new Date( start.getTime() + i * hours * 60 * 60 * 1000 )
+	);
+
+// A formatter that ignores its context reads Los Angeles here, and the instants
+// below land on a different calendar day there than in Tokyo. The runtime locale
+// stays en-US, so a German label can only come from the supplied context.
+
+describe( 'getFormatter with a host formatting context', () => {
+	const daily = toSeries( every( new Date( '2026-08-02T12:00:00Z' ), 14, 24 ) );
+
+	it( 'labels date ticks in the supplied locale', () => {
+		const format = getFormatter( daily, undefined, { locale: 'de-DE' } );
+
+		expect( format( Date.parse( '2026-08-02T12:00:00Z' ) ) ).toBe( '2. Aug.' );
+	} );
+
+	it( "labels date ticks on the supplied zone's calendar day", () => {
+		const format = getFormatter( daily, undefined, { timeZone: 'Asia/Tokyo' } );
+
+		// 00:30 on Aug 3 in Tokyo, still Aug 2 in the runtime zone.
+		expect( format( Date.parse( '2026-08-02T15:30:00Z' ) ) ).toBe( 'Aug 3' );
+	} );
+
+	// Aug 3 in UTC and Aug 2 in the pinned zone, so this fails without the
+	// environment rather than passing under the script's own `TZ=UTC`.
+	it( 'falls back to the runtime locale and zone when given no context', () => {
+		expect( getFormatter( daily )( Date.parse( '2026-08-03T03:00:00Z' ) ) ).toBe( 'Aug 2' );
+	} );
+
+	it( "anchors the date label to the supplied zone's first hour of the day", () => {
+		const hourly = toSeries( every( tokyoMidnight( 2026, 7, 1 ), 72, 1 ) );
+		const format = getFormatter( hourly, undefined, { timeZone: 'Asia/Tokyo' } );
+
+		// Midnight in Tokyo, 08:00 the previous day in the runtime zone.
+		expect( format( tokyoMidnight( 2026, 7, 2 ).getTime() ) ).toBe( 'Aug 2' );
+		// Midnight in the runtime zone, 16:00 in Tokyo.
+		expect( format( Date.parse( '2026-08-02T07:00:00Z' ) ) ).toBe( '4 PM' );
+	} );
+
+	// The boundary test runs before the label formatter, so its own guard is the
+	// only thing standing between a bad point and a throw out of `formatToParts`.
+	it( 'renders past an invalid date on a boundary format', () => {
+		const hourly = toSeries( every( tokyoMidnight( 2026, 7, 1 ), 72, 1 ) );
+		const format = getFormatter( hourly, undefined, { timeZone: 'Asia/Tokyo' } );
+
+		expect( format( NaN ) ).toBe( 'Invalid Date' );
+	} );
+
+	it( 'anchors the year label to January in the supplied zone', () => {
+		const monthly = toSeries(
+			Array.from( { length: 12 }, ( _, i ) => tokyoMidnight( 2025, 7 + i ) )
+		);
+		const format = getFormatter( monthly, undefined, { timeZone: 'Asia/Tokyo' } );
+
+		// January 1 in Tokyo, December 31 in the runtime zone.
+		expect( format( tokyoMidnight( 2026, 0 ).getTime() ) ).toBe( '2026' );
+		expect( format( tokyoMidnight( 2026, 1 ).getTime() ) ).toBe( 'Feb' );
+	} );
+} );
+
+describe( 'getBandTickValues with a host formatting context', () => {
+	// The shape the Stats payload arrives in: buckets aligned to UTC, which a
+	// half-hour zone reads at :30, so none of them is ever an exact midnight.
+	it( 'dates the day on a half-hour zone, where no bucket reads midnight', () => {
+		const domain = every( new Date( '2026-08-01T00:00:00Z' ), 72, 1 );
+		const format = getFormatter( toSeries( domain ), undefined, { timeZone: 'Asia/Kolkata' } );
+
+		const labels = getBandTickValues( domain, format, 4 ).map( date => format( date.getTime() ) );
+
+		expect( labels ).toEqual( [ 'Aug 2', 'Aug 3', 'Aug 4' ] );
+	} );
+
+	it( "puts the year tick on the supplied zone's January bucket", () => {
+		const domain = Array.from( { length: 12 }, ( _, i ) => tokyoMidnight( 2025, 7 + i ) );
+		const format = getFormatter( toSeries( domain ), undefined, {
+			locale: 'de-DE',
+			timeZone: 'Asia/Tokyo',
+		} );
+
+		const values = getBandTickValues( domain, format, 4 );
+
+		expect( values.find( date => format( date.getTime() ) === '2026' ) ).toEqual(
+			tokyoMidnight( 2026, 0 )
+		);
+	} );
+} );

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

@@ -0,0 +1,267 @@
+/**
+ * @jest-environment <rootDir>/tests/environment-los-angeles.mjs
+ */
+import { dailySeries, hourlySeries } from '../../../test-utils/series-fixtures';
+import { buildTimeAxisOptions } from '../time-axis-options';
+
+const TOKYO = { timeZone: 'Asia/Tokyo' };
+
+const build = ( overrides: Partial< Parameters< typeof buildTimeAxisOptions >[ 0 ] > = {} ) =>
+	buildTimeAxisOptions( {
+		dataSorted: dailySeries( '2026-08-01T15:00:00Z', 30 ),
+		width: 600,
+		axisOptions: { tickResolution: 'day' },
+		scaleDomain: undefined,
+		zoomDomain: undefined,
+		formatting: TOKYO,
+		...overrides,
+	} );
+
+describe( 'buildTimeAxisOptions', () => {
+	it( 'selects tick values instead of leaving the count to d3', () => {
+		const axis = build();
+
+		expect( Array.isArray( axis.tickValues ) ).toBe( true );
+		expect( ( axis.tickValues as Date[] ).length ).toBeGreaterThan( 1 );
+	} );
+
+	it( 'confines tick values to the zoom window', () => {
+		const zoomDomain: [ Date, Date ] = [
+			new Date( '2026-08-10T15:00:00Z' ),
+			new Date( '2026-08-14T15:00:00Z' ),
+		];
+
+		const ticks = build( { zoomDomain } ).tickValues as Date[];
+
+		expect( ticks.length ).toBeGreaterThan( 0 );
+		for ( const tick of ticks ) {
+			expect( tick.getTime() ).toBeGreaterThanOrEqual( zoomDomain[ 0 ].getTime() );
+			expect( tick.getTime() ).toBeLessThanOrEqual( zoomDomain[ 1 ].getTime() );
+		}
+	} );
+
+	it( 'prefers the zoom window over a caller scale domain', () => {
+		const scaleDomain: [ Date, Date ] = [
+			new Date( '2026-08-01T15:00:00Z' ),
+			new Date( '2026-08-30T15:00:00Z' ),
+		];
+		const zoomDomain: [ Date, Date ] = [
+			new Date( '2026-08-10T15:00:00Z' ),
+			new Date( '2026-08-12T15:00:00Z' ),
+		];
+
+		const ticks = build( { scaleDomain, zoomDomain } ).tickValues as Date[];
+
+		expect( ticks.length ).toBeGreaterThan( 0 );
+		for ( const tick of ticks ) {
+			expect( tick.getTime() ).toBeLessThanOrEqual( zoomDomain[ 1 ].getTime() );
+		}
+	} );
+
+	it( 'confines tick values to a caller scale domain when there is no zoom', () => {
+		const scaleDomain: [ Date, Date ] = [
+			new Date( '2026-08-05T15:00:00Z' ),
+			new Date( '2026-08-08T15:00:00Z' ),
+		];
+
+		const ticks = build( { scaleDomain } ).tickValues as Date[];
+
+		expect( ticks.length ).toBeGreaterThan( 0 );
+		for ( const tick of ticks ) {
+			expect( tick.getTime() ).toBeGreaterThanOrEqual( scaleDomain[ 0 ].getTime() );
+			expect( tick.getTime() ).toBeLessThanOrEqual( scaleDomain[ 1 ].getTime() );
+		}
+	} );
+
+	it( 'caps the selection at a caller numTicks', () => {
+		const axis = build( { axisOptions: { tickResolution: 'day', numTicks: 3 } } );
+
+		expect( ( axis.tickValues as Date[] ).length ).toBeLessThanOrEqual( 3 );
+	} );
+
+	it( 'caps the selection by width when no numTicks is given', () => {
+		const narrow = build( { width: 180 } ).tickValues as Date[];
+		const wide = build( { width: 900 } ).tickValues as Date[];
+
+		expect( narrow.length ).toBeLessThan( wide.length );
+	} );
+
+	it( 'selects nothing when the caller supplies its own tickFormat', () => {
+		const axis = build( {
+			axisOptions: { tickResolution: 'day', tickFormat: () => 'x' },
+		} );
+
+		expect( axis.tickValues ).toBeUndefined();
+		expect( axis.tickFormat?.( new Date(), 0, [] ) ).toBe( 'x' );
+		expect( typeof axis.numTicks ).toBe( 'number' );
+	} );
+
+	it( 'fits a caller tickFormat to the width rather than leaving visx its fixed default', () => {
+		const isoDay = ( value: unknown ) => new Date( Number( value ) ).toISOString().slice( 0, 10 );
+
+		const narrow = build( {
+			width: 180,
+			axisOptions: { tickResolution: 'day', tickFormat: isoDay },
+		} );
+		const wide = build( {
+			width: 900,
+			axisOptions: { tickResolution: 'day', tickFormat: isoDay },
+		} );
+
+		expect( narrow.numTicks ).toBeLessThan( wide.numTicks as number );
+	} );
+
+	it( "keeps a caller's numTicks on the tickFormat branch", () => {
+		const axis = build( {
+			axisOptions: { tickResolution: 'day', tickFormat: () => 'x', numTicks: 2 },
+		} );
+
+		expect( axis.numTicks ).toBe( 2 );
+	} );
+
+	it( 'narrows the format to the zoom window on a multi-year dataset', () => {
+		const axis = build( {
+			dataSorted: dailySeries( '2023-01-01T15:00:00Z', 1100 ),
+			zoomDomain: [ new Date( '2024-03-01T15:00:00Z' ), new Date( '2024-08-01T15:00:00Z' ) ],
+		} );
+
+		const labels = new Set(
+			( axis.tickValues as Date[] ).map( tick => axis.tickFormat?.( tick, 0, [] ) )
+		);
+
+		expect( labels.size ).toBeGreaterThan( 1 );
+	} );
+
+	it( 'selects ticks only from the series the chart renders', () => {
+		const dataSorted = [
+			{ ...dailySeries( '2026-06-01T15:00:00Z', 90 )[ 0 ], label: 'hidden' },
+			{ ...dailySeries( '2026-08-01T15:00:00Z', 5 )[ 0 ], label: 'shown' },
+		];
+
+		const ticks = build( {
+			dataSorted,
+			isSeriesRendered: series => series.label === 'shown',
+		} ).tickValues as Date[];
+
+		const rendered = dataSorted[ 1 ].data.map( point => Number( point.date ) );
+		expect( ticks.length ).toBeGreaterThan( 1 );
+		for ( const tick of ticks ) {
+			expect( rendered ).toContain( tick.getTime() );
+		}
+	} );
+
+	it( "lets a caller's own tickValues win", () => {
+		const mine = [ new Date( '2026-08-05T15:00:00Z' ) ];
+
+		const axis = build( { axisOptions: { tickResolution: 'day', tickValues: mine } } );
+
+		expect( axis.tickValues ).toBe( mine );
+	} );
+
+	it( 'labels ticks in the host time zone', () => {
+		// 2026-08-02T15:30Z is Aug 2 in Los Angeles and Aug 3 in Tokyo.
+		const axis = build( { formatting: { locale: 'de-DE', timeZone: 'Asia/Tokyo' } } );
+
+		expect( axis.tickFormat?.( new Date( '2026-08-02T15:30:00Z' ), 0, [] ) ).toBe( '3. Aug.' );
+	} );
+
+	it( 'falls back to the runtime locale and zone when no formatting is supplied', () => {
+		const axis = build( { formatting: {} } );
+
+		expect( axis.tickFormat?.( new Date( '2026-08-02T15:30:00Z' ), 0, [] ) ).toBe( 'Aug 2' );
+	} );
+	it( 'keeps its own selection when a caller passes tickValues as undefined', () => {
+		const axis = build( { axisOptions: { tickResolution: 'day', tickValues: undefined } } );
+
+		expect( ( axis.tickValues as Date[] ).length ).toBeGreaterThan( 1 );
+	} );
+
+	it( 'keeps its width-fitted count when a caller passes numTicks as undefined', () => {
+		const isoDay = ( value: unknown ) => new Date( Number( value ) ).toISOString().slice( 0, 10 );
+
+		const axis = build( {
+			width: 180,
+			axisOptions: { tickResolution: 'day', tickFormat: isoDay, numTicks: undefined },
+		} );
+
+		expect( axis.numTicks ).toBeLessThan( 10 );
+	} );
+
+	it( 'keeps its defaults when a caller passes orientation and display as undefined', () => {
+		const axis = build( { axisOptions: { orientation: undefined, display: undefined } } );
+
+		expect( axis.orientation ).toBe( 'bottom' );
+		expect( axis.display ).toBe( true );
+	} );
+
+	it( 'still lets a caller set orientation and display', () => {
+		const axis = build( { axisOptions: { orientation: 'top', display: false } } );
+
+		expect( axis.orientation ).toBe( 'top' );
+		expect( axis.display ).toBe( false );
+	} );
+
+	it( 'hands visx a width-fitted count rather than an empty selection', () => {
+		const axis = build( {
+			zoomDomain: [ new Date( '2027-01-01T00:00:00Z' ), new Date( '2027-01-02T00:00:00Z' ) ],
+		} );
+
+		expect( axis.tickValues ).toBeUndefined();
+		expect( typeof axis.numTicks ).toBe( 'number' );
+	} );
+
+	it( 'accepts a numeric scale domain', () => {
+		const axis = build( {
+			scaleDomain: [ Date.parse( '2026-08-05T15:00:00Z' ), Date.parse( '2026-08-08T15:00:00Z' ) ],
+		} );
+
+		const ticks = axis.tickValues as Date[];
+		expect( ticks.length ).toBeGreaterThan( 0 );
+		for ( const tick of ticks ) {
+			expect( tick.getTime() ).toBeGreaterThanOrEqual( Date.parse( '2026-08-05T15:00:00Z' ) );
+			expect( tick.getTime() ).toBeLessThanOrEqual( Date.parse( '2026-08-08T15:00:00Z' ) );
+		}
+	} );
+
+	it( "keeps a caller's orientation and display", () => {
+		const axis = build( {
+			axisOptions: { tickResolution: 'day', orientation: 'top', display: false },
+		} );
+
+		expect( axis.orientation ).toBe( 'top' );
+		expect( axis.display ).toBe( false );
+	} );
+
+	it( 'sends no numTicks when it selects the tick values itself', () => {
+		expect( 'numTicks' in build() ).toBe( false );
+	} );
+
+	// A date the host could not parse arrives as `new Date( NaN )`. Left in the
+	// span it turns the domain, the formatter and the tick count into NaN, and
+	// visx reads the resulting `numTicks: 0` as "label nothing".
+	it( 'still labels the axis when a series ends on an unparsable date', () => {
+		const [ series ] = dailySeries( '2026-08-01T15:00:00Z', 4 );
+		const withBadDate = [
+			{ ...series, data: [ ...series.data, { date: new Date( NaN ), value: 5 } ] },
+		];
+
+		const options = build( { dataSorted: withBadDate } );
+
+		expect( options.tickValues?.length ).toBeGreaterThan( 0 );
+		expect( options.numTicks ?? 1 ).toBeGreaterThan( 0 );
+	} );
+
+	it( 'reads the resolution from the series it renders, not the hidden ones', () => {
+		const dataSorted = [
+			{ ...hourlySeries( '2026-08-01T00:00:00Z', 48 )[ 0 ], label: 'hidden' },
+			{ ...dailySeries( '2026-08-01T15:00:00Z', 5 )[ 0 ], label: 'shown' },
+		];
+
+		const axis = build( { dataSorted, isSeriesRendered: series => series.label === 'shown' } );
+
+		// A daily label, not one of the hidden series' hours.
+		expect( axis.tickFormat?.( new Date( '2026-08-02T15:00:00Z' ), 0, [] ) ).not.toMatch(
+			/(AM|PM|Uhr)/
+		);
+	} );
+} );