@automattic/charts 1.12.0 → 2.0.1

package/src/charts/conversion-funnel-chart/conversion-funnel-chart.module.scss

@@ -16,7 +16,7 @@
 	text-overflow: ellipsis;
 	font-size: var(--wpds-typography-font-size-xl, 18px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-medium, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 	margin: 0;
 }
@@ -26,7 +26,7 @@
 	text-overflow: ellipsis;
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-medium, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 	margin: 0;
 }
@@ -56,7 +56,7 @@
 .step-label {
 	color: var(--a8c-charts-color-label-secondary, var(--wpds-color-foreground-content-neutral-weak, #707070));
 	font-size: var(--wpds-typography-font-size-sm, 12px);
-	font-weight: var(--wpds-typography-font-weight-regular, 400);
+	font-weight: var(--wpds-typography-font-weight-default, 400);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
 	white-space: nowrap;
 	overflow: hidden;
@@ -66,7 +66,7 @@
 .step-rate {
 	color: var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e));
 	font-size: var(--wpds-typography-font-size-md, 13px);
-	font-weight: var(--wpds-typography-font-weight-medium, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
 }
 
@@ -105,7 +105,7 @@
 	// Override .visx-tooltip inline styles.
 	border-radius: var(--wpds-border-radius-md, 4px) !important;
 	padding: var(--wpds-dimension-padding-md, 12px) !important;
-	box-shadow: var(--wpds-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005) !important;
+	box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005) !important;
 
 }
 
@@ -113,7 +113,7 @@
 	color: var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e));
 	font-size: var(--wpds-typography-font-size-sm, 12px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-regular, 400);
+	font-weight: var(--wpds-typography-font-weight-default, 400);
 	line-height: var(--wpds-typography-line-height-xs, 16px);
 }
 
@@ -121,7 +121,7 @@
 	color: var(--a8c-charts-color-label, var(--wpds-color-foreground-content-neutral, #1e1e1e));
 	font-size: var(--wpds-typography-font-size-md, 13px);
 	font-style: normal;
-	font-weight: var(--wpds-typography-font-weight-medium, 499);
+	font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 	line-height: var(--wpds-typography-line-height-sm, 20px);
 }
 

package/src/charts/line-chart/line-chart.module.scss

@@ -24,7 +24,7 @@
 	}
 
 	&__tooltip-date {
-		font-weight: var(--wpds-typography-font-weight-medium, 499);
+		font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 		padding-bottom: var(--wpds-dimension-padding-md, 12px);
 	}
 
@@ -33,7 +33,7 @@
 	}
 
 	&__tooltip-label {
-		font-weight: var(--wpds-typography-font-weight-medium, 499);
+		font-weight: var(--wpds-typography-font-weight-emphasis, 499);
 		padding-right: var(--wpds-dimension-padding-lg, 16px);
 	}
 
@@ -65,7 +65,7 @@
 		border: none;
 		border-radius: var(--wpds-border-radius-md, 4px);
 		font-size: var(--wpds-typography-font-size-md, 13px);
-		box-shadow: var(--wpds-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
+		box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
 		position: fixed;
 		// Without margin set, the popover has margin:auto which upsets the
 		// positioning relative to the trigger button. A gap token is appropriate

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

@@ -29,7 +29,7 @@ import {
 	useGlobalChartsContext,
 	useGlobalChartsTheme,
 } from '../../providers';
-import { attachSubComponents, resolveCssVariable } from '../../utils';
+import { attachSubComponents } from '../../utils';
 import { useChartChildren } from '../private/chart-composition';
 import { ChartLayout } from '../private/chart-layout';
 import { DefaultGlyph } from '../private/default-glyph';
@@ -192,11 +192,9 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 		const legendPosition = legend.position ?? 'bottom';
 
 		const providerTheme = useGlobalChartsTheme();
-		// Gradient stops apply this as an SVG attribute, where CSS var() cannot
-		// resolve, so resolve the WPDS token to a concrete value first.
-		const resolvedBackgroundColor =
-			resolveCssVariable( providerTheme.backgroundColor ) ?? providerTheme.backgroundColor;
 		const theme = useXYChartTheme( data );
+		// Gradient stops apply this as an SVG attribute, where CSS var() cannot resolve. useXYChartTheme has already resolved the same role inside its memo, so read it back rather than paying another getComputedStyle on every render.
+		const resolvedBackgroundColor = theme.backgroundColor ?? providerTheme.backgroundColor;
 		const chartId = useChartId( providedChartId );
 		const chartRef = useRef< HTMLDivElement >( null );
 		const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
@@ -287,7 +285,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: {
@@ -296,7 +295,7 @@ const LineChartInternal = forwardRef< SingleChartRef, LineChartProps >(
 						numTicks: guessOptimalNumTicks( dataSorted, width, formatter ),
 						tickFormat: formatter,
 						display: true,
-						...options?.axis?.x,
+						...xAxisOptions,
 					},
 					y: {
 						orientation: 'left' as const,

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

@@ -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
 		} );
 

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,427 @@
+import { getBandTickValues, getBucketResolution, 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 ) );
+
+// The test script pins TZ and locale, 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' );
+	} );
+
+	it( 'keeps month ticks for monthly buckets spanning several years', () => {
+		const monthlyDates = Array.from(
+			{ length: 36 },
+			( _, i ) => new Date( Date.UTC( 2024, i, 1 ) )
+		);
+		const formatter = getFormatter( toSeries( monthlyDates ) );
+
+		// Year ticks here would render the same year for every tick the band scale
+		// samples out of a calendar year.
+		expect( formatter( new Date( '2024-10-01T00:00:00' ).getTime() ) ).toBe( 'Oct' );
+		expect( formatter( new Date( '2025-01-01T00:00:00' ).getTime() ) ).toBe( '2025' );
+	} );
+
+	it( 'uses year ticks for inferred yearly buckets that do not start in January', () => {
+		const formatter = getFormatter(
+			toSeries( [ new Date( '2023-07-01T00:00:00' ), new Date( '2024-07-01T00:00:00' ) ] )
+		);
+
+		// The month regime would print a bare "Jul" for both.
+		expect( formatter( new Date( '2023-07-01T00:00:00' ).getTime() ) ).toBe( '2023' );
+		expect( formatter( new Date( '2024-07-01T00:00:00' ).getTime() ) ).toBe( '2024' );
+	} );
+
+	it( 'ignores series with no dated points when measuring the span', () => {
+		const formatter = getFormatter( [
+			...toSeries( dailyDates( new Date( '2024-01-01T00:00:00' ), 14 ) ),
+			...toSeries( [] ),
+		] );
+
+		// An empty comparison series must not turn the span into NaN, which would
+		// fall through every span check to year ticks.
+		expect( formatter( new Date( '2024-01-03T00:00:00' ).getTime() ) ).toMatch( /Jan 3/ );
+	} );
+
+	it( 'falls back to date ticks when nothing is dated', () => {
+		const formatter = getFormatter( toSeries( [] ) );
+
+		expect( formatter( new Date( '2024-01-03T00:00:00' ).getTime() ) ).toMatch( /Jan 3/ );
+	} );
+
+	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' );
+		} );
+	} );
+} );
+
+describe( 'getBucketResolution', () => {
+	it( 'infers hourly buckets from sub-daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) ) )
+		).toBe( 'hour' );
+	} );
+
+	it( 'infers daily buckets from daily spacing', () => {
+		expect(
+			getBucketResolution( toSeries( dailyDates( new Date( '2026-08-01T00:00:00' ), 5 ) ) )
+		).toBe( 'day' );
+	} );
+
+	it( 'infers daily buckets from weekly spacing, which labels the same way', () => {
+		const weeklyDates = Array.from(
+			{ length: 5 },
+			( _, i ) => new Date( Date.UTC( 2026, 0, 5 + i * 7 ) )
+		);
+
+		expect( getBucketResolution( toSeries( weeklyDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'infers monthly buckets from a shortest-month gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2026-02-01T00:00:00' ), new Date( '2026-03-01T00:00:00' ) ] )
+			)
+		).toBe( 'month' );
+	} );
+
+	it( 'infers yearly buckets from a yearly gap', () => {
+		expect(
+			getBucketResolution(
+				toSeries( [ new Date( '2025-06-01T00:00:00' ), new Date( '2026-06-01T00:00:00' ) ] )
+			)
+		).toBe( 'year' );
+	} );
+
+	it( 'keeps a daily gap across spring-forward out of the hourly bucket', () => {
+		const start = new Date( '2026-03-08T00:00:00' );
+		const dstDates = [ 0, 23, 47 ].map(
+			offsetHours => new Date( start.getTime() + offsetHours * 60 * 60 * 1000 )
+		);
+
+		expect( getBucketResolution( toSeries( dstDates ) ) ).toBe( 'day' );
+	} );
+
+	it( 'reports daily buckets when no series has two points', () => {
+		// Unmeasurable spacing reads as Infinity, which must not be mistaken for a
+		// very coarse bucket.
+		expect( getBucketResolution( toSeries( [ new Date( '2026-08-02T00:00:00' ) ] ) ) ).toBe(
+			'day'
+		);
+	} );
+
+	it( 'reports a declared resolution over the measured spacing', () => {
+		const hourly = toSeries( hourlyDates( new Date( '2026-08-02T00:00:00' ), 6 ) );
+
+		expect( getBucketResolution( hourly, 'month' ) ).toBe( 'month' );
+	} );
+
+	it( 'reports a declared weekly resolution as daily', () => {
+		// Weeks and days are both calendar-date buckets as far as labelling goes,
+		// and 'week' is not a label format of its own.
+		expect( getBucketResolution( toSeries( [] ), 'week' ) ).toBe( 'day' );
+	} );
+} );
+
+describe( 'tick format anchors', () => {
+	// The band axis steers ticks onto boundaries using the predicate the format
+	// hangs off itself. If the two ever disagree, the axis aims at buckets that
+	// do not actually print the coarser label.
+	it( 'marks exactly the buckets whose label carries the coarser unit', () => {
+		const hourly = Array.from( { length: 48 }, ( _, i ) => new Date( 2026, 7, 2, i ) );
+		const hourFormat = getFormatter( toSeries( hourly ) );
+
+		expect( hourFormat.isAnchor ).toBeDefined();
+		hourly.forEach( date => {
+			const isDateLabel = ! /(AM|PM)/.test( hourFormat( date.getTime() ) );
+			expect( hourFormat.isAnchor( date ) ).toBe( isDateLabel );
+		} );
+
+		const monthly = Array.from( { length: 36 }, ( _, i ) => new Date( 2023, 6 + i, 1 ) );
+		const monthFormat = getFormatter( toSeries( monthly ) );
+
+		expect( monthFormat.isAnchor ).toBeDefined();
+		monthly.forEach( date => {
+			const isYearLabel = /^\d{4}$/.test( monthFormat( date.getTime() ) );
+			expect( monthFormat.isAnchor( date ) ).toBe( isYearLabel );
+		} );
+	} );
+} );
+
+describe( 'getBandTickValues', () => {
+	const monthlyDomain = ( year: number, month: number, months: number ) =>
+		Array.from( { length: months }, ( _, i ) => new Date( year, month + i, 1 ) );
+
+	const hourlyDomain = ( start: Date, hours: number ) =>
+		Array.from( { length: hours }, ( _, i ) => new Date( start.getTime() + i * 60 * 60 * 1000 ) );
+
+	const labelsFor = ( domain: Date[], maxTicks = 4 ) => {
+		const formatter = getFormatter( toSeries( domain ) );
+		return getBandTickValues( domain, formatter, maxTicks ).map( date =>
+			formatter( date.getTime() )
+		);
+	};
+
+	it( 'shifts the sampling offset onto January for a monthly series starting mid-year', () => {
+		// Sampling from index 0 gives Aug, Nov, Feb, May, Aug — no year at all on a
+		// series that crosses one, and "Aug" twice.
+		expect( labelsFor( monthlyDomain( 2025, 7, 13 ) ) ).toContain( '2026' );
+	} );
+
+	it( 'lands on every January of a multi-year monthly series that starts mid-year', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ) ) ).toEqual( [ '2024', '2025', '2026' ] );
+	} );
+
+	it( 'keeps the dated midnight ticks for sub-daily data spanning days', () => {
+		// Index sampling already lands here; this pins that the steering keeps it.
+		expect( labelsFor( hourlyDomain( new Date( 2026, 7, 2 ), 48 ) ) ).toEqual( [
+			'Aug 2',
+			'12 PM',
+			'Aug 3',
+			'12 PM',
+		] );
+	} );
+
+	it( 'steps whole days once a sub-daily span is too long to date any other way', () => {
+		// No step inside a day fits four ticks across a week, so the offset sweep
+		// alone would leave every tick but the first a bare hour on an unnamed day.
+		expect( labelsFor( hourlyDomain( new Date( 2026, 7, 2 ), 168 ) ) ).toEqual( [
+			'Aug 2',
+			'Aug 4',
+			'Aug 6',
+			'Aug 8',
+		] );
+	} );
+
+	it( 'steps whole years once a monthly span is too long to reach January any other way', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 120 ) ) ).toEqual( [
+			'2024',
+			'2027',
+			'2030',
+			'2033',
+		] );
+	} );
+
+	it( 'still names a year at the lowest tick counts a caller can ask for', () => {
+		// An anchor outranks a denser axis, so without a step that reaches two of
+		// them a two-tick axis would settle for a single January.
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ), 2 ) ).toEqual( [ '2024', '2026' ] );
+		expect( labelsFor( monthlyDomain( 2023, 6, 36 ), 3 ) ).toEqual( [ '2024', '2025', '2026' ] );
+	} );
+
+	it( 'never repeats a label on adjacent ticks', () => {
+		// 49 buckets put every fourth tick a whole year apart, so sampling by index
+		// spells the same month five times over: Feb, Feb, Feb, Feb, Feb.
+		const labels = labelsFor( monthlyDomain( 2023, 1, 49 ) );
+
+		expect( labels.some( ( label, i ) => i > 0 && label === labels[ i - 1 ] ) ).toBe( false );
+	} );
+
+	it( 'keeps the axis dense when only a sparser one could reach an anchor', () => {
+		// Ranking anchors above everything picked the two ticks that happened to be
+		// Januaries and dropped the rest of the axis with them.
+		expect( labelsFor( monthlyDomain( 2023, 3, 30 ) ) ).toEqual( [ 'Apr', '2024', 'Oct', 'Jul' ] );
+	} );
+
+	it( 'names the single year of a short series without thinning the axis to it', () => {
+		expect( labelsFor( monthlyDomain( 2023, 6, 9 ) ) ).toEqual( [ 'Jul', 'Oct', '2024' ] );
+	} );
+
+	it( 'reaches anchors that sit an uneven number of buckets apart', () => {
+		// A spring-forward day is 23 hourly buckets, not 24, so a fixed stride
+		// slides off midnight and leaves the rest of the week on bare hours.
+		const domain: Date[] = [];
+		for ( let day = 0; day < 7; day++ ) {
+			for ( let hour = 0; hour < 24; hour++ ) {
+				if ( day !== 2 || hour !== 2 ) {
+					domain.push( new Date( 2026, 2, 6 + day, hour ) );
+				}
+			}
+		}
+
+		expect( labelsFor( domain ) ).toEqual( [ 'Mar 6', 'Mar 8', 'Mar 10', 'Mar 12' ] );
+	} );
+
+	it( 'keeps the whole domain when it already fits', () => {
+		const domain = monthlyDomain( 2023, 0, 4 );
+
+		expect( getBandTickValues( domain, String, 4 ) ).toEqual( domain );
+	} );
+
+	it( 'never exceeds the requested tick count', () => {
+		const domain = monthlyDomain( 2023, 6, 36 );
+
+		expect( getBandTickValues( domain, String, 4 ).length ).toBeLessThanOrEqual( 4 );
+		expect( getBandTickValues( domain, String, 7 ).length ).toBeLessThanOrEqual( 7 );
+	} );
+
+	it( 'returns nothing for an empty domain', () => {
+		expect( getBandTickValues( [], String, 4 ) ).toEqual( [] );
+	} );
+} );