@automattic/charts 1.11.0 → 2.0.0

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

@@ -179,6 +179,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			onPointerMove = undefined,
 			onPointerOut = undefined,
 			zoomable = false,
+			rescaleYOnVisibilityChange = true,
 			children,
 			gridVisibility,
 			gap = 'md',
@@ -186,6 +187,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		ref
 	) => {
 		const legendInteractive = legend.interactive ?? false;
+		const legendCollapseGroups = legend.collapseGroups ?? false;
 		const legendShape = legend.shape ?? 'line';
 		const legendPosition = legend.position ?? 'bottom';
 
@@ -252,6 +254,28 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			return seriesWithVisibility.every( ( { isVisible } ) => ! isVisible );
 		}, [ seriesWithVisibility ] );
 
+		// When the interactive legend can hide series and rescaling is opted out, pin the value axis
+		// to the full data range so it stays put as series are toggled instead of visx rescaling the
+		// domain to whatever is currently visible and making the axis jump. Default is to rescale,
+		// matching the pre-existing behaviour and AreaChart's `rescaleYOnVisibilityChange`.
+		const stableYDomain = useMemo< [ number, number ] | undefined >( () => {
+			if ( ! legendInteractive || rescaleYOnVisibilityChange ) {
+				return undefined;
+			}
+			let min = Infinity;
+			let max = -Infinity;
+			for ( const series of dataSorted ) {
+				for ( const point of series.data ?? [] ) {
+					const value = point?.value;
+					if ( typeof value === 'number' && Number.isFinite( value ) ) {
+						min = Math.min( min, value );
+						max = Math.max( max, value );
+					}
+				}
+			}
+			return min < max ? [ min, max ] : undefined;
+		}, [ legendInteractive, rescaleYOnVisibilityChange, dataSorted ] );
+
 		// Use the keyboard navigation hook
 		const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
 			selectedIndex,
@@ -263,7 +287,8 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		} );
 
 		const chartOptions = useMemo( () => {
-			const formatter = options?.axis?.x?.tickFormat || getFormatter( dataSorted );
+			const { tickResolution, ...xAxisOptions } = options?.axis?.x ?? {};
+			const formatter = xAxisOptions.tickFormat || getFormatter( dataSorted, tickResolution );
 
 			return {
 				axis: {
@@ -272,7 +297,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 						numTicks: guessOptimalNumTicks( dataSorted, width, formatter ),
 						tickFormat: formatter,
 						display: true,
-						...options?.axis?.x,
+						...xAxisOptions,
 					},
 					y: {
 						orientation: 'left' as const,
@@ -291,10 +316,11 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 					type: 'linear' as const,
 					nice: true,
 					zero: false,
+					...( stableYDomain ? { domain: stableYDomain } : {} ),
 					...options?.yScale,
 				},
 			};
-		}, [ options, dataSorted, width, zoom.domain ] );
+		}, [ options, dataSorted, width, zoom.domain, stableYDomain ] );
 
 		const tooltipRenderGlyph = useMemo( () => {
 			return ( props: GlyphProps< DataPointDate > ) => {
@@ -328,9 +354,10 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 			() => ( {
 				withGlyph: withLegendGlyph,
 				glyphSize: Math.max( 0, toNumber( glyphStyle?.radius ) ?? 4 ),
+				collapseGroups: legendCollapseGroups,
 				renderGlyph,
 			} ),
-			[ withLegendGlyph, glyphStyle?.radius, renderGlyph ]
+			[ withLegendGlyph, glyphStyle?.radius, legendCollapseGroups, renderGlyph ]
 		);
 
 		// Create legend items using the reusable hook
@@ -444,9 +471,18 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 											onPointerOut={ onPointerOut }
 											pointerEventsDataKey="nearest"
 										>
-											{ gridVisibility !== 'none' && <Grid columns={ false } numTicks={ 4 } /> }
-											{ chartOptions.axis.x.display && <Axis { ...chartOptions.axis.x } /> }
-											{ chartOptions.axis.y.display && <Axis { ...chartOptions.axis.y } /> }
+											{ /* With every series hidden there is no data to scale against, so the grid and
+											     axes are dropped while the empty state stands in — otherwise they render
+											     squished at the top. */ }
+											{ ! allSeriesHidden && gridVisibility !== 'none' && (
+												<Grid columns={ false } numTicks={ 4 } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.x.display && (
+												<Axis { ...chartOptions.axis.x } />
+											) }
+											{ ! allSeriesHidden && chartOptions.axis.y.display && (
+												<Axis { ...chartOptions.axis.y } />
+											) }
 
 											{ allSeriesHidden ? (
 												<SvgEmptyState

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

@@ -1,6 +1,6 @@
 /* eslint-disable react/jsx-no-bind */
 
-import { render, screen, waitFor } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { GlyphDiamond } from '@visx/glyph';
 import { createElement, createRef } from 'react';
@@ -436,7 +436,48 @@ describe( 'LineChart', () => {
 			expect( ticks.length ).toBeGreaterThan( 1 );
 		} );
 
+		test( 'renders hour ticks when tickResolution declares the buckets sub-daily.', () => {
+			renderWithTheme( {
+				width: 800,
+				options: { axis: { x: { tickResolution: 'hour' } } },
+				data: [
+					{
+						label: 'Series A',
+						// A day apart: spacing inference would read this as daily buckets.
+						data: [
+							{ date: new Date( '2024-01-01T00:00:00' ), value: 10 },
+							{ date: new Date( '2024-01-02T00:00:00' ), value: 20 },
+						],
+					},
+				],
+			} );
+
+			const ticks = screen.getAllByText( /\d+\s(AM|PM)/ );
+			expect( ticks.length ).toBeGreaterThan( 1 );
+		} );
+
 		test( 'renders ticks in short date format.', () => {
+			renderWithTheme( {
+				width: 800,
+				data: [
+					{
+						label: 'Series A',
+						// Weekly resolution: fine enough to keep full dates on the ticks.
+						data: Array.from( { length: 16 }, ( _, i ) => ( {
+							date: new Date( Date.UTC( 2024, 0, 1 + i * 7 ) ),
+							value: 10 + i,
+						} ) ),
+					},
+				],
+			} );
+
+			const ticks = screen.getAllByText(
+				/^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d+$/
+			);
+			expect( ticks.length ).toBeGreaterThan( 1 );
+		} );
+
+		test( 'renders month ticks for month-or-coarser buckets within a year.', () => {
 			renderWithTheme( {
 				width: 800,
 				data: [
@@ -453,9 +494,7 @@ describe( 'LineChart', () => {
 				],
 			} );
 
-			const ticks = screen.getAllByText(
-				/^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d+$/
-			);
+			const ticks = screen.getAllByText( /^(Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$/ );
 			expect( ticks.length ).toBeGreaterThan( 1 );
 		} );
 
@@ -502,7 +541,8 @@ describe( 'LineChart', () => {
 				],
 			} );
 
-			const ticks = screen.getAllByText( /(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct) \d+/ );
+			// Roughly monthly buckets render month ticks under the resolution-aware formatter.
+			const ticks = screen.getAllByText( /^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct)$/ );
 			expect( ticks.length ).toBeLessThan( 6 ); // Not much space
 		} );
 
@@ -1294,4 +1334,193 @@ describe( 'LineChart', () => {
 			'url(#chart-zoom-clip-zoomtest)'
 		);
 	} );
+
+	describe( 'Legend group collapsing', () => {
+		const comparisonPair = [
+			{
+				label: 'Views',
+				group: 'views',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 20, label: 'Jan 2' },
+				],
+			},
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 8, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 16, label: 'Jan 2' },
+				],
+			},
+		];
+
+		it( 'renders one legend item per series by default', () => {
+			renderWithTheme( {
+				showLegend: true,
+				chartId: 'legend-groups-default',
+				data: comparisonPair,
+			} );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Views — previous' ) ).toBeInTheDocument();
+		} );
+
+		it( 'collapses a group to one item when legend.collapseGroups is set', () => {
+			renderWithTheme( {
+				showLegend: true,
+				legend: { collapseGroups: true },
+				chartId: 'legend-groups-collapsed',
+				data: comparisonPair,
+			} );
+
+			expect( screen.getByText( 'Views' ) ).toBeInTheDocument();
+			expect( screen.queryByText( 'Views — previous' ) ).not.toBeInTheDocument();
+		} );
+
+		it( 'toggles only the clicked series when interactive without collapseGroups', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'legend-groups-interactive',
+				data: comparisonPair,
+			} );
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+
+			expect( buttons[ 0 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+			expect( buttons[ 1 ] ).toHaveAttribute( 'aria-pressed', 'true' );
+		} );
+
+		it( 'toggles the whole group when interactive with collapseGroups', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true, collapseGroups: true },
+				chartId: 'legend-groups-interactive-collapsed',
+				data: comparisonPair,
+			} );
+
+			const buttons = screen.getAllByRole( 'button' );
+			expect( buttons ).toHaveLength( 1 );
+
+			await user.click( buttons[ 0 ] );
+
+			expect( buttons[ 0 ] ).toHaveAttribute( 'aria-pressed', 'false' );
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
+	} );
+
+	describe( 'Interactive Legend — value axis', () => {
+		const twoSeries = [
+			{
+				label: 'Views',
+				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: 'Visitors',
+				data: [
+					{ date: new Date( '2024-01-01' ), value: 100, label: 'Jan 1' },
+					{ date: new Date( '2024-01-02' ), value: 200, label: 'Jan 2' },
+				],
+				options: {},
+			},
+		];
+		// Bare numbers inside the plot (scoped via the chart's grid role, away from visx's
+		// off-screen text-measurement SVGs) are value-axis ticks: the series labels carry no digits
+		// and the empty-state message is text-only.
+		const numericTick = /^[\d,]+$/;
+
+		it( 'pins the value axis when rescaleYOnVisibilityChange is false', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				rescaleYOnVisibilityChange: false,
+				chartId: 'line-stable-axis',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			const ticksBefore = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksBefore.length ).toBeGreaterThan( 0 );
+
+			// Hide the high-range Visitors series; with a pinned domain the axis keeps its ticks.
+			await user.click( screen.getAllByRole( 'button' )[ 1 ] );
+
+			const ticksAfter = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksAfter ).toEqual( ticksBefore );
+		} );
+
+		it( 'rescales the value axis by default when a series is toggled off', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'line-rescale-axis',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			const ticksBefore = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksBefore.length ).toBeGreaterThan( 0 );
+
+			// Default preserves the pre-existing behaviour: hiding the high-range Visitors series
+			// lets the axis rescale to the remaining Views range, so its ticks change.
+			await user.click( screen.getAllByRole( 'button' )[ 1 ] );
+
+			const ticksAfter = within( chart )
+				.getAllByText( numericTick )
+				.map( el => el.textContent )
+				.sort();
+			expect( ticksAfter ).not.toEqual( ticksBefore );
+		} );
+
+		it( 'drops the axes when all series are hidden so they do not collapse', async () => {
+			const user = userEvent.setup();
+
+			renderWithTheme( {
+				showLegend: true,
+				legend: { interactive: true },
+				chartId: 'line-hidden-axes',
+				data: twoSeries,
+			} );
+
+			const chart = screen.getByRole( 'grid' );
+			expect( within( chart ).getAllByText( numericTick ).length ).toBeGreaterThan( 0 );
+
+			const buttons = screen.getAllByRole( 'button' );
+			await user.click( buttons[ 0 ] );
+			await user.click( buttons[ 1 ] );
+
+			// With no visible data the value scale would collapse, so the axes are removed rather
+			// than rendered squished at the top — no tick labels remain.
+			expect( within( chart ).queryAllByText( numericTick ) ).toHaveLength( 0 );
+			expect(
+				screen.getByText( /all series are hidden.*click legend items to show data/i )
+			).toBeInTheDocument();
+		} );
+	} );
 } );

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

@@ -2,6 +2,7 @@ import type {
 	BaseChartProps,
 	DataPointDate,
 	SeriesData,
+	SeriesChartLegendConfig,
 	AnnotationStyles,
 	DataPoint,
 } from '../../types';
@@ -28,6 +29,10 @@ export type RenderLineGlyphProps< Datum extends object > = GlyphProps< Datum > &
 };
 
 export interface LineChartProps extends BaseChartProps< SeriesData[] > {
+	/**
+	 * Legend configuration. Supports `collapseGroups` on top of the shared options.
+	 */
+	legend?: SeriesChartLegendConfig;
 	withGradientFill: boolean;
 	smoothing?: boolean;
 	curveType?: CurveType;
@@ -47,6 +52,15 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] > {
 	 * button appears in the top-right of the chart while zoomed.
 	 */
 	zoomable?: boolean;
+	/**
+	 * Whether the Y axis rescales to fit only the visible series when series are
+	 * hidden or shown through the interactive legend.
+	 * Defaults to `true` (the pre-existing behaviour). Set to `false` to pin the Y
+	 * axis to the full data extent so hiding series does not move the chart's
+	 * baseline — useful for comparison charts. Matches `AreaChart`.
+	 * @default true
+	 */
+	rescaleYOnVisibilityChange?: boolean;
 	children?: ReactNode;
 }
 

package/src/charts/pie-semi-circle-chart/pie-semi-circle-chart.module.scss

@@ -6,7 +6,7 @@
 	}
 
 	.label {
-		font-weight: var(--wpds-typography-font-weight-medium, 499);
+		font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 		font-size: var(--wpds-typography-font-size-lg, 16px);
 	}
 

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

@@ -0,0 +1,182 @@
+import { 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;
+
+const hourlyDates = ( start: Date, hours: number ): Date[] =>
+	Array.from( { length: hours }, ( _, i ) => new Date( start.getTime() + i * 60 * 60 * 1000 ) );
+
+const dailyDates = ( start: Date, days: number ): Date[] =>
+	Array.from( { length: days }, ( _, i ) => new Date( start.getTime() + i * 24 * 60 * 60 * 1000 ) );
+
+// TZ is pinned to UTC by the test script, so local formatting is deterministic.
+describe( 'getFormatter', () => {
+	it( 'uses hour ticks within a single day', () => {
+		const formatter = getFormatter(
+			toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 24 ) )
+		);
+
+		expect( formatter( new Date( '2026-08-02T13:00:00' ).getTime() ) ).toMatch( /1\sPM/ );
+	} );
+
+	it( 'uses hour ticks with dates at midnight for sub-daily data spanning multiple days', () => {
+		const formatter = getFormatter(
+			toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 48 ) )
+		);
+
+		expect( formatter( new Date( '2026-08-03T00:00:00' ).getTime() ) ).toMatch( /Aug 3/ );
+		expect( formatter( new Date( '2026-08-02T13:00:00' ).getTime() ) ).toMatch( /1\sPM/ );
+	} );
+
+	it( 'keeps hour ticks up to a full week of sub-daily data', () => {
+		const formatter = getFormatter(
+			toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 24 * 7 + 1 ) )
+		);
+
+		expect( formatter( new Date( '2026-08-05T13:00:00' ).getTime() ) ).toMatch( /1\sPM/ );
+	} );
+
+	it( 'keeps date ticks for a two-point daily series spanning exactly a day', () => {
+		const formatter = getFormatter(
+			toSeries( dailyDates( new Date( '2026-08-01T00:00:00' ), 2 ) )
+		);
+
+		expect( formatter( new Date( '2026-08-02T00:00:00' ).getTime() ) ).toMatch( /Aug 2/ );
+	} );
+
+	it( 'keeps date ticks for daily data over the same multi-day span', () => {
+		const formatter = getFormatter(
+			toSeries( dailyDates( new Date( '2026-08-01T00:00:00' ), 3 ) )
+		);
+
+		expect( formatter( new Date( '2026-08-02T00:00:00' ).getTime() ) ).toMatch( /Aug 2/ );
+		expect( formatter( new Date( '2026-08-02T13:00:00' ).getTime() ) ).not.toMatch( /PM/ );
+	} );
+
+	it( 'keeps date ticks for daily buckets across a spring-forward transition', () => {
+		// A 23-hour first gap, as a daily series straddling spring-forward
+		// produces, must not demote the series to the sub-daily regime.
+		const start = new Date( '2026-03-08T00:00:00' );
+		const dstDates = [ 0, 23, 47, 71 ].map(
+			offsetHours => new Date( start.getTime() + offsetHours * 60 * 60 * 1000 )
+		);
+		const formatter = getFormatter( toSeries( dstDates ) );
+
+		expect( formatter( dstDates[ 2 ].getTime() ) ).not.toMatch( /AM|PM/ );
+		expect( formatter( dstDates[ 2 ].getTime() ) ).toMatch( /Mar/ );
+	} );
+
+	it( 'keeps date ticks when no series has two points', () => {
+		const formatter = getFormatter( [
+			...toSeries( [ new Date( '2026-03-01T00:00:00' ) ] ),
+			...toSeries( [ new Date( '2026-03-04T00:00:00' ) ] ),
+		] );
+
+		expect( formatter( new Date( '2026-03-02T00:00:00' ).getTime() ) ).toMatch( /Mar 2/ );
+	} );
+
+	it( 'uses month ticks for buckets exactly a shortest-month apart', () => {
+		const formatter = getFormatter(
+			toSeries( [
+				new Date( '2026-02-01T00:00:00' ),
+				new Date( '2026-03-01T00:00:00' ),
+				new Date( '2026-04-01T00:00:00' ),
+			] )
+		);
+
+		expect( formatter( new Date( '2026-03-01T00:00:00' ).getTime() ) ).toBe( 'Mar' );
+	} );
+
+	it( 'uses month ticks with the year at January for monthly buckets', () => {
+		const monthlyDates = Array.from(
+			{ length: 13 },
+			( _, i ) => new Date( Date.UTC( 2025, 7 + i, 1 ) )
+		);
+		const formatter = getFormatter( toSeries( monthlyDates ) );
+
+		expect( formatter( new Date( '2025-09-01T00:00:00' ).getTime() ) ).toBe( 'Sep' );
+		expect( formatter( new Date( '2026-01-01T00:00:00' ).getTime() ) ).toBe( '2026' );
+	} );
+
+	it( 'keeps date ticks for weekly buckets within a year', () => {
+		const weeklyDates = Array.from(
+			{ length: 20 },
+			( _, i ) => new Date( Date.UTC( 2026, 0, 5 + i * 7 ) )
+		);
+		const formatter = getFormatter( toSeries( weeklyDates ) );
+
+		expect( formatter( new Date( '2026-03-02T00:00:00' ).getTime() ) ).toMatch( /Mar 2/ );
+	} );
+
+	it( 'uses year ticks beyond a year', () => {
+		const yearly = getFormatter(
+			toSeries( [ new Date( '2020-01-01T00:00:00' ), new Date( '2026-01-01T00:00:00' ) ] )
+		);
+
+		expect( yearly( new Date( '2023-01-01T00:00:00' ).getTime() ) ).toBe( '2023' );
+	} );
+
+	describe( 'with an explicit tickResolution', () => {
+		it( 'uses hour ticks for two hourly points a day apart, where spacing would read as daily', () => {
+			const formatter = getFormatter(
+				toSeries( [ new Date( '2026-08-01T00:00:00' ), new Date( '2026-08-02T00:00:00' ) ] ),
+				'hour'
+			);
+
+			expect( formatter( new Date( '2026-08-01T13:00:00' ).getTime() ) ).toMatch( /1\sPM/ );
+		} );
+
+		it( 'uses date ticks for a lone daily point, where spacing is unknowable', () => {
+			const formatter = getFormatter( toSeries( [ new Date( '2026-08-02T00:00:00' ) ] ), 'day' );
+
+			expect( formatter( new Date( '2026-08-02T00:00:00' ).getTime() ) ).toMatch( /Aug 2/ );
+		} );
+
+		it( 'uses month ticks for monthly buckets regardless of their measured gaps', () => {
+			const formatter = getFormatter(
+				toSeries( [ new Date( '2026-02-01T00:00:00' ), new Date( '2026-03-01T00:00:00' ) ] ),
+				'month'
+			);
+
+			expect( formatter( new Date( '2026-03-01T00:00:00' ).getTime() ) ).toBe( 'Mar' );
+		} );
+
+		it( 'uses date ticks for weekly buckets', () => {
+			const weeklyDates = Array.from(
+				{ length: 8 },
+				( _, i ) => new Date( Date.UTC( 2026, 0, 5 + i * 7 ) )
+			);
+			const formatter = getFormatter( toSeries( weeklyDates ), 'week' );
+
+			expect( formatter( new Date( '2026-01-12T00:00:00' ).getTime() ) ).toMatch( /Jan 12/ );
+		} );
+
+		it( 'uses year ticks for a pair of yearly buckets', () => {
+			const formatter = getFormatter(
+				toSeries( [ new Date( '2025-01-01T00:00:00' ), new Date( '2026-01-01T00:00:00' ) ] ),
+				'year'
+			);
+
+			expect( formatter( new Date( '2025-01-01T00:00:00' ).getTime() ) ).toBe( '2025' );
+			expect( formatter( new Date( '2026-01-01T00:00:00' ).getTime() ) ).toBe( '2026' );
+		} );
+
+		it( 'uses year ticks for yearly buckets that do not start in January', () => {
+			const formatter = getFormatter(
+				toSeries( [ new Date( '2025-06-01T00:00:00' ), new Date( '2026-06-01T00:00:00' ) ] ),
+				'year'
+			);
+
+			expect( formatter( new Date( '2025-06-01T00:00:00' ).getTime() ) ).toBe( '2025' );
+			expect( formatter( new Date( '2026-06-01T00:00:00' ).getTime() ) ).toBe( '2026' );
+		} );
+	} );
+} );