@automattic/charts 3.2.0 → 4.1.0

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)/
+		);
+	} );
+} );

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

@@ -0,0 +1,153 @@
+import { getFormatter, getMaxTicksForWidth, getTimeAxisTickValues } from '../time-axis';
+import type { SeriesData, TickResolution } from '../../../types';
+
+// Tick placement depends on the shape of the data, not just its values, and a
+// hand-written fixture only covers the shapes someone thought of. Sweep the
+// shapes instead, and assert what has to hold for every one of them.
+
+const HOUR = 3600 * 1000;
+const ZONES = [ 'UTC', 'Asia/Tokyo', 'America/New_York', 'Australia/Lord_Howe', 'Pacific/Chatham' ];
+const RESOLUTIONS: ( TickResolution | undefined )[] = [
+	undefined,
+	'hour',
+	'day',
+	'week',
+	'month',
+	'year',
+];
+const SHAPES = [ 'even', 'gap', 'burst', 'scattered', 'repeated', 'minutes' ] as const;
+
+// A seeded generator, so a failure names a run that reproduces.
+let seed = 1;
+const random = () => ( seed = ( seed * 1103515245 + 12345 ) % 2147483648 ) / 2147483648;
+const oneOf = < T >( values: readonly T[] ): T => values[ Math.floor( random() * values.length ) ];
+
+const makeDates = (): Date[] => {
+	const start = Date.UTC(
+		2025,
+		Math.floor( random() * 12 ),
+		1 + Math.floor( random() * 27 ),
+		Math.floor( random() * 24 )
+	);
+	const shape = oneOf( SHAPES );
+	const stepHours = oneOf( [ 1, 6, 24, 24 * 7, 24 * 30 ] );
+	const count = 1 + Math.floor( random() * 200 );
+	const times: number[] = [];
+
+	for ( let index = 0; index < count; index++ ) {
+		switch ( shape ) {
+			case 'gap':
+				times.push( start + ( index < count / 2 ? index : index + 500 ) * stepHours * HOUR );
+				break;
+			case 'burst':
+				times.push(
+					start + Math.floor( index / 5 ) * stepHours * 50 * HOUR + ( index % 5 ) * HOUR
+				);
+				break;
+			case 'scattered':
+				times.push( start + Math.floor( random() * 5000 ) * HOUR );
+				break;
+			case 'repeated':
+				times.push( start + Math.floor( index / 3 ) * stepHours * HOUR );
+				break;
+			case 'minutes':
+				times.push( start + index * 60 * 1000 );
+				break;
+			default:
+				times.push( start + index * stepHours * HOUR );
+		}
+	}
+
+	return times.sort( ( a, b ) => a - b ).map( time => new Date( time ) );
+};
+
+const makeSeries = (): SeriesData[] =>
+	Array.from( { length: 1 + Math.floor( random() * 3 ) }, ( _, index ) => ( {
+		label: `series ${ index }`,
+		data: makeDates().map( ( date, position ) => ( { date, value: position } ) ),
+	} ) );
+
+describe( 'time axis tick invariants', () => {
+	it( 'holds across data shapes, zones, resolutions and widths', () => {
+		const failures: string[] = [];
+
+		for ( let run = 0; run < 2000; run++ ) {
+			const data = makeSeries();
+			const timeZone = oneOf( ZONES );
+			const resolution = oneOf( RESOLUTIONS );
+			const maxTicks = getMaxTicksForWidth( oneOf( [ 60, 120, 320, 700, 900, 1400 ] ) );
+			const formatter = getFormatter( data, resolution, { timeZone } );
+
+			const points = [
+				...new Set(
+					data.flatMap( series =>
+						series.data.map( point => ( point as { date: Date } ).date.getTime() )
+					)
+				),
+			].sort( ( a, b ) => a - b );
+
+			// Half the runs read a domain rather than the whole extent, and some of
+			// those reach well past the data, which is what a brush dragged over a
+			// sparse stretch hands the axis.
+			let domain: [ Date, Date ] | undefined;
+			if ( random() < 0.5 && points.length > 1 ) {
+				const one = points[ Math.floor( random() * points.length ) ];
+				const other = points[ Math.floor( random() * points.length ) ];
+				const padding = random() < 0.5 ? Math.floor( random() * 2000 ) * HOUR : 0;
+				domain = [
+					new Date( Math.min( one, other ) - padding ),
+					new Date( Math.max( one, other ) + padding ),
+				];
+			}
+
+			const ticks = getTimeAxisTickValues( data, domain, formatter, maxTicks );
+			if ( ! ticks ) {
+				continue;
+			}
+
+			const visible = domain
+				? points.filter( time => time >= domain[ 0 ].getTime() && time <= domain[ 1 ].getTime() )
+				: points;
+			if ( ! visible.length ) {
+				continue;
+			}
+
+			const times = ticks.map( tick => tick.getTime() );
+			const labels = ticks.map( tick => formatter( tick.getTime() ) );
+			// Ticks answer to the scale, which spans the domain when there is one.
+			const first = domain ? domain[ 0 ].getTime() : visible[ 0 ];
+			const last = domain ? domain[ 1 ].getTime() : visible[ visible.length - 1 ];
+			const note = ( why: string ) =>
+				failures.push(
+					`run ${ run }: ${ why } (points ${ visible.length }, maxTicks ${ maxTicks }, ${ timeZone }, resolution ${ resolution })`
+				);
+
+			if ( times.some( ( time, index ) => index > 0 && time <= times[ index - 1 ] ) ) {
+				note( 'ticks are not strictly ascending' );
+			}
+			if ( times.length > maxTicks ) {
+				note( `${ times.length } ticks over a budget of ${ maxTicks }` );
+			}
+			if ( times.some( time => time < first || time > last ) ) {
+				note( 'a tick falls outside the domain' );
+			}
+			if ( labels.some( ( label, index ) => index > 0 && label === labels[ index - 1 ] ) ) {
+				note( 'two adjacent ticks carry the same label' );
+			}
+
+			// One label is `span / maxTicks` wide, so a closer pair overlaps.
+			const span = last - first;
+			if ( span > 0 && times.length > 1 ) {
+				const closest = Math.min(
+					...times.slice( 1 ).map( ( time, index ) => time - times[ index ] )
+				);
+				const room = span / maxTicks;
+				if ( closest < room * 0.9 ) {
+					note( `two ticks share ${ Math.round( ( closest / room ) * 100 ) }% of a label's width` );
+				}
+			}
+		}
+
+		expect( failures.slice( 0, 10 ) ).toEqual( [] );
+	} );
+} );