@automattic/charts 4.0.0 → 4.1.0

package/src/hooks/test/use-chart-margin.test.tsx

@@ -9,6 +9,13 @@ jest.mock( '../../utils/get-longest-tick-width', () => ( {
 	getLongestTickWidth: ( ...args: unknown[] ) => mockGetLongestTickWidth( ...args ),
 } ) );
 
+// jsdom has no getComputedTextLength, so the real measurement always returns null.
+const mockGetEdgeTickWidths = jest.fn();
+jest.mock( '../../utils/get-edge-tick-widths', () => ( {
+	...jest.requireActual( '../../utils/get-edge-tick-widths' ),
+	getEdgeTickWidths: ( ...args: unknown[] ) => mockGetEdgeTickWidths( ...args ),
+} ) );
+
 describe( 'useChartMargin', () => {
 	const baseTheme = {
 		axisStyles: {
@@ -43,6 +50,8 @@ describe( 'useChartMargin', () => {
 	beforeEach( () => {
 		mockGetLongestTickWidth.mockReset();
 		mockGetLongestTickWidth.mockReturnValue( 40 );
+		mockGetEdgeTickWidths.mockReset();
+		mockGetEdgeTickWidths.mockReturnValue( { first: 0, last: 0 } );
 	} );
 
 	it( 'calculates left margin for left y axis', () => {
@@ -62,7 +71,7 @@ describe( 'useChartMargin', () => {
 		expect( mockGetLongestTickWidth ).toHaveBeenCalledWith(
 			expect.any( Array ),
 			options.axis.y.tickFormat,
-			theme.axisStyles.y.left.axisLabel
+			{ fontSize: '12px' }
 		);
 		// 40 label width + 8 tick length + ceil(11 * 0.25) label dx offset
 		expect( result.current.left ).toBe( 51 );
@@ -85,7 +94,7 @@ describe( 'useChartMargin', () => {
 		expect( mockGetLongestTickWidth ).toHaveBeenCalledWith(
 			expect.any( Array ),
 			options.axis.y.tickFormat,
-			theme.axisStyles.y.right.axisLabel
+			{ fontSize: '12px' }
 		);
 		// 40 label width + 8 tick length + ceil(11 * 0.25) label dx offset
 		expect( result.current.right ).toBe( 51 );
@@ -108,7 +117,7 @@ describe( 'useChartMargin', () => {
 		expect( mockGetLongestTickWidth ).toHaveBeenCalledWith(
 			[ 0, 1000 ],
 			options.axis.y.tickFormat,
-			theme.axisStyles.y.left.axisLabel
+			{ fontSize: '12px' }
 		);
 	} );
 
@@ -185,6 +194,167 @@ describe( 'useChartMargin', () => {
 		expect( result.current.bottom ).toBe( 25 );
 	} );
 
+	describe( 'x-axis edge tick labels', () => {
+		const tickFormat = ( value: number ) => new Date( value ).toDateString();
+		const tickValues = [ 1, 2, 3 ];
+		const datedXOptions = ( xOverrides = {} ) => ( {
+			...optionsBase,
+			axis: { ...optionsBase.axis, x: { tickValues, tickFormat, ...xOverrides } },
+		} );
+
+		it( 'reserves half of the last label on the right', () => {
+			mockGetEdgeTickWidths.mockReturnValue( { first: 0, last: 60 } );
+
+			const { result } = renderHook( () =>
+				useChartMargin( 300, datedXOptions(), data, baseTheme )
+			);
+
+			expect( result.current.right ).toBe( 30 );
+		} );
+
+		it( 'keeps the default right margin when the last label fits inside it', () => {
+			mockGetEdgeTickWidths.mockReturnValue( { first: 0, last: 30 } );
+
+			const { result } = renderHook( () =>
+				useChartMargin( 300, datedXOptions(), data, baseTheme )
+			);
+
+			expect( result.current.right ).toBe( 20 );
+		} );
+
+		it( 'widens the left margin past the y-axis reservation when the first label needs it', () => {
+			mockGetEdgeTickWidths.mockReturnValue( { first: 120, last: 0 } );
+
+			const { result } = renderHook( () =>
+				useChartMargin( 300, datedXOptions(), data, baseTheme )
+			);
+
+			// 60 for the label's overhanging half, over the 51 the y-axis ticks need.
+			expect( result.current.left ).toBe( 60 );
+		} );
+
+		it( 'measures the axis tick values with the x tick label style', () => {
+			const theme = {
+				...baseTheme,
+				axisStyles: {
+					...baseTheme.axisStyles,
+					x: {
+						bottom: { tickLabel: { fontSize: 11 }, tickLength: 8 } as unknown as never,
+						top: {} as unknown as never,
+					},
+				},
+			} as XYChartTheme;
+
+			renderHook( () => useChartMargin( 300, datedXOptions(), data, theme ) );
+
+			expect( mockGetEdgeTickWidths ).toHaveBeenCalledWith( tickValues, tickFormat, {
+				fontSize: '11px',
+			} );
+		} );
+
+		it( 'falls back to the raw tick label style when its font size is a relative unit', () => {
+			const theme = {
+				...baseTheme,
+				axisStyles: {
+					...baseTheme.axisStyles,
+					x: {
+						bottom: { tickLabel: { fontSize: '0.875rem' }, tickLength: 8 } as unknown as never,
+						top: {} as unknown as never,
+					},
+				},
+			} as XYChartTheme;
+
+			renderHook( () => useChartMargin( 300, datedXOptions(), data, theme ) );
+
+			expect( mockGetEdgeTickWidths ).toHaveBeenCalledWith( tickValues, tickFormat, {
+				fontSize: '0.875rem',
+			} );
+		} );
+
+		it( 'reserves the edge labels on a top x axis too', () => {
+			mockGetEdgeTickWidths.mockReturnValue( { first: 120, last: 60 } );
+
+			const { result } = renderHook( () =>
+				useChartMargin( 300, datedXOptions( { orientation: 'top' } ), data, baseTheme )
+			);
+
+			expect( result.current.right ).toBe( 30 );
+			expect( result.current.left ).toBe( 60 );
+		} );
+
+		it( 'reserves nothing for a hidden x axis', () => {
+			mockGetEdgeTickWidths.mockReturnValue( { first: 120, last: 60 } );
+
+			const { result } = renderHook( () =>
+				useChartMargin( 300, datedXOptions( { display: false } ), data, baseTheme )
+			);
+
+			expect( mockGetEdgeTickWidths ).not.toHaveBeenCalled();
+			expect( result.current.right ).toBe( 20 );
+			expect( result.current.left ).toBe( 51 );
+		} );
+	} );
+
+	describe( 'real measurement', () => {
+		// Everything else here mocks the measurer out; this block runs it for real,
+		// so that a width that never reaches the margin would fail something.
+		const actual = jest.requireActual( '../../utils/get-edge-tick-widths' );
+		type Measurable = { getComputedTextLength?: () => number };
+
+		afterEach( () => {
+			delete ( window.SVGElement.prototype as Measurable ).getComputedTextLength;
+		} );
+
+		it( 'turns a measured edge label into a reserved margin', () => {
+			// jsdom ships no getComputedTextLength, so @visx/text cannot measure at all.
+			( window.SVGElement.prototype as Measurable ).getComputedTextLength = function (
+				this: SVGElement
+			) {
+				return ( this.textContent ?? '' ).length * 8;
+			};
+			mockGetEdgeTickWidths.mockImplementation( actual.getEdgeTickWidths );
+
+			const options = {
+				...optionsBase,
+				axis: {
+					...optionsBase.axis,
+					x: {
+						tickValues: [ 1, 2 ],
+						tickFormat: ( _value: number, index: number ) =>
+							index === 0 ? 'AA' : 'MEASURED-LAST',
+					},
+				},
+			};
+
+			const { result } = renderHook( () => useChartMargin( 300, options, data, baseTheme ) );
+
+			// 'MEASURED-LAST' is 13 characters, so 104px wide, and half of it is reserved.
+			expect( result.current.right ).toBe( 52 );
+		} );
+	} );
+
+	describe( 'y axis gutter', () => {
+		it( 'measures a caller-pinned domain rather than the data range', () => {
+			const options = { ...optionsBase, yScale: { domain: [ 0, 1 ] as [ number, number ] } };
+
+			renderHook( () => useChartMargin( 300, options, data, baseTheme ) );
+
+			const ticks = mockGetLongestTickWidth.mock.calls[ 0 ][ 0 ] as number[];
+			expect( Math.max( ...ticks ) ).toBeLessThanOrEqual( 1 );
+		} );
+
+		it( 'reserves no gutter for a hidden y axis', () => {
+			const options = {
+				...optionsBase,
+				axis: { ...optionsBase.axis, y: { ...optionsBase.axis.y, display: false } },
+			};
+
+			const { result } = renderHook( () => useChartMargin( 300, options, data, baseTheme ) );
+
+			expect( result.current.left ).toBe( 20 );
+		} );
+	} );
+
 	describe( 'horizontal y ticks', () => {
 		const horizontalOptions = ( tickFormat: ( value: string | number ) => string ) => ( {
 			...optionsBase,

package/src/hooks/use-chart-data-transform.ts

@@ -1,4 +1,7 @@
 import { useMemo } from 'react';
+// Imported from the module rather than the `providers` barrel: that barrel pulls
+// `use-chart-registration`, which imports this file's own barrel back.
+import { useChartFormatting } from '../providers/chart-context/hooks/use-chart-formatting';
 import { parseAsLocalDate } from '../utils';
 import type { SeriesData } from '../types';
 
@@ -7,7 +10,7 @@ import type { SeriesData } from '../types';
  *
  * This hook extracts the common data transformation logic used in both line-chart
  * and bar-chart components. It:
- * 1. Parses date strings into Date objects using parseAsLocalDate
+ * 1. Parses date strings into Date objects, dated in the provider's time zone
  * 2. Sorts data points by date when date properties are present
  * 3. Returns the original data unchanged when no date properties are found
  *
@@ -15,6 +18,10 @@ import type { SeriesData } from '../types';
  * @return {SeriesData[]} The transformed and sorted data
  */
 export const useChartDataTransform = ( data: SeriesData[] ) => {
+	// A naive `dateString` names no zone, so without this it would be read in the
+	// viewer's and then relabeled in the host's, and the two never cancel.
+	const { timeZone } = useChartFormatting();
+
 	return useMemo( () => {
 		// Check if the first data point has date or dateString properties
 		const firstPoint = data?.[ 0 ]?.data?.[ 0 ];
@@ -35,7 +42,7 @@ export const useChartDataTransform = ( data: SeriesData[] ) => {
 					if ( 'date' in point && point.date ) {
 						date = point.date;
 					} else if ( 'dateString' in point && point.dateString ) {
-						date = parseAsLocalDate( point.dateString );
+						date = parseAsLocalDate( point.dateString, timeZone );
 					}
 
 					return {
@@ -48,5 +55,5 @@ export const useChartDataTransform = ( data: SeriesData[] ) => {
 					return a.date.getTime() - b.date.getTime();
 				} ),
 		} ) );
-	}, [ data ] );
+	}, [ data, timeZone ] );
 };

package/src/hooks/use-chart-margin.tsx

@@ -1,6 +1,6 @@
 import { createScale, getTicks } from '@visx/scale';
 import { useMemo } from 'react';
-import { getLongestTickWidth, resolveFontSize } from '../utils';
+import { getEdgeTickWidths, getLongestTickWidth, resolveFontSize } from '../utils';
 import type { BaseChartProps, DataPointDate, SeriesData } from '../types';
 import type { XYChartTheme } from '@visx/xychart';
 
@@ -50,6 +50,33 @@ const DEFAULT_TICK_LENGTH = 8;
  */
 const DEFAULT_Y_TICK_WIDTH = 40;
 
+type LabelStyle = { fontSize?: number | string; letterSpacing?: number | string };
+
+/**
+ * Copy a label style with its lengths spelled out in px.
+ *
+ * `getStringWidth` applies the style through CSSOM. Blink resolves a bare number
+ * on an SVG `<text>`, but that is its own leniency rather than the CSS rule, and
+ * `buildChartTheme` hands us bare numbers.
+ *
+ * @param style - Raw label style from the theme.
+ * @return The same style with px-qualified lengths.
+ */
+const toMeasurableStyle = < T extends LabelStyle >( style?: T ) => {
+	if ( ! style ) {
+		return style;
+	}
+
+	const fontSize = resolveFontSize( style.fontSize );
+	const { letterSpacing } = style;
+
+	return {
+		...style,
+		...( fontSize === undefined ? {} : { fontSize: `${ fontSize }px` } ),
+		...( typeof letterSpacing === 'number' ? { letterSpacing: `${ letterSpacing }px` } : {} ),
+	};
+};
+
 const getXAxisLabelMetrics = ( theme: XYChartTheme, orientation: 'top' | 'bottom' ) => {
 	const xAxisStyles =
 		orientation === 'top' ? theme.axisStyles?.x?.top : theme.axisStyles?.x?.bottom;
@@ -61,7 +88,7 @@ const getXAxisLabelMetrics = ( theme: XYChartTheme, orientation: 'top' | 'bottom
 
 	const tickLength = xAxisStyles?.tickLength ?? DEFAULT_TICK_LENGTH;
 
-	return { fontSize, tickLength };
+	return { fontSize, tickLength, tickLabelStyle: toMeasurableStyle( xAxisStyles?.tickLabel ) };
 };
 
 export const useChartMargin = (
@@ -88,7 +115,9 @@ export const useChartMargin = (
 		const maxY = Math.max( ...allDataPoints.map( d => d.value ) );
 		const yScale = createScale( {
 			...options.yScale,
-			domain: [ minY, maxY ],
+			// A pinned domain is what the axis actually renders, so measure those
+			// ticks; the data's range would size the gutter for narrower labels.
+			domain: options.yScale?.domain ?? [ minY, maxY ],
 			range: [ height, 0 ],
 		} );
 
@@ -111,7 +140,7 @@ export const useChartMargin = (
 		const yTickWidth = getLongestTickWidth(
 			yTicks,
 			options.axis?.y?.tickFormat,
-			yAxisStyles.axisLabel
+			toMeasurableStyle( yAxisStyles.axisLabel )
 		);
 		// visx's default axis theme pushes y-axis tick labels a further 0.25em
 		// away from the axis (dx of -0.25em on the left, 0.25em on the right), so
@@ -125,17 +154,20 @@ export const useChartMargin = (
 			( yAxisStyles?.tickLength ?? 0 ) +
 			Math.ceil( yTickLabelFontSize * 0.25 );
 
-		if ( yAxisOrientation === 'right' ) {
-			defaultMargin.right = yMarginValue;
-		} else {
-			defaultMargin.left = yMarginValue;
+		// A hidden y axis reserves nothing; its gutter belongs to the plot area.
+		if ( options.axis?.y?.display !== false ) {
+			if ( yAxisOrientation === 'right' ) {
+				defaultMargin.right = yMarginValue;
+			} else {
+				defaultMargin.left = yMarginValue;
+			}
 		}
 
 		// Dynamically compute X-axis margin (bottom by default, or top if orientation is 'top').
 		// This mirrors Y-axis behavior where margin is based on label size and tick length,
 		// but keeps the padding minimal so consumers can control container spacing themselves.
 		const xOrientation = options.axis?.x?.orientation === 'top' ? 'top' : 'bottom';
-		const { fontSize, tickLength } = getXAxisLabelMetrics( theme, xOrientation );
+		const { fontSize, tickLength, tickLabelStyle } = getXAxisLabelMetrics( theme, xOrientation );
 		const computedXMargin = fontSize + tickLength;
 
 		if ( xOrientation === 'top' ) {
@@ -145,6 +177,19 @@ export const useChartMargin = (
 			defaultMargin.bottom = Math.max( defaultMargin.bottom, computedXMargin );
 		}
 
+		// An X-axis label is centered on its tick, so the ones at either end of the
+		// scale hang half their width outside the plot area and clip at the SVG edge.
+		if ( options.axis?.x?.display !== false ) {
+			const { first, last } = getEdgeTickWidths(
+				options.axis?.x?.tickValues ?? [],
+				options.axis?.x?.tickFormat,
+				tickLabelStyle
+			);
+
+			defaultMargin.left = Math.max( defaultMargin.left, Math.ceil( first / 2 ) );
+			defaultMargin.right = Math.max( defaultMargin.right, Math.ceil( last / 2 ) );
+		}
+
 		return defaultMargin;
 	}, [ options, theme, yTicks ] );
 };

package/src/index.ts

@@ -10,6 +10,7 @@ export {
 	HeatmapChart,
 	HeatmapChartUnresponsive,
 	buildCalendarHeatmapData,
+	useCalendarHeatmapData,
 } from './charts/heatmap-chart';
 export { LeaderboardChart, LeaderboardChartUnresponsive } from './charts/leaderboard-chart';
 export { LineChart, LineChartUnresponsive } from './charts/line-chart';
@@ -113,6 +114,7 @@ export type {
 	HeatmapColumn,
 	HeatmapCell,
 	HeatmapTooltipData,
+	CalendarHeatmapOptions,
 	CalendarHeatmapResult,
 } from './charts/heatmap-chart';
 export type { LeaderboardChartProps } from './charts/leaderboard-chart';
@@ -138,3 +140,5 @@ export {
 export * from './utils/color-utils';
 export type { MetricValueType } from './utils';
 export type { BucketInfo } from './types';
+
+export type { CrosshairStyle } from './visx/types';

package/src/test-utils/zoned-parsing-suite.ts

@@ -0,0 +1,90 @@
+import { parseAsLocalDate } from '../utils/date-parsing';
+
+// `@wordpress/jest-console` registers the matcher but ships no types for it.
+declare global {
+	// eslint-disable-next-line @typescript-eslint/no-namespace
+	namespace jest {
+		interface Matchers< R > {
+			toHaveWarnedWith( ...args: unknown[] ): R;
+		}
+	}
+}
+
+// Every case asserts an absolute instant, so running the suite from more than one
+// worker zone is what proves the result does not depend on the viewer's.
+const CASES: Array< [ string, string, string ] > = [
+	// The shape the Stats payload gives for a day bucket.
+	[ '2026-08-02', 'Asia/Tokyo', '2026-08-01T15:00:00.000Z' ],
+	[ '2026-08-02 09:30:00', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	[ '2026-08-02T09:30:00', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	// Santiago springs forward at midnight, deleting this reading entirely.
+	[ '2026-09-06', 'America/Santiago', '2026-09-06T04:00:00.000Z' ],
+	// Berlin's gap runs the other way, its offset growing rather than shrinking, which is
+	// the shape most of Europe and North America has. Only this case tells the smaller of
+	// the two candidate offsets apart from the later probe.
+	[ '2026-03-29 02:30:00', 'Europe/Berlin', '2026-03-29T01:30:00.000Z' ],
+	// And Santiago falls back at midnight, so this reading happens twice.
+	[ '2026-04-04 23:00:00', 'America/Santiago', '2026-04-05T02:00:00.000Z' ],
+	// Which of the two an overlap resolves to follows the sign of the offset, so a zone
+	// east of UTC settles on the other one. Auckland is where this PR's own stories sit.
+	[ '2026-04-05 02:30:00', 'Pacific/Auckland', '2026-04-04T14:30:00.000Z' ],
+	// Hours past a fall-back, where the first offset probe lands on the wrong side
+	// of the transition and only the second one is right.
+	[ '2026-11-01 08:00:00', 'America/Los_Angeles', '2026-11-01T16:00:00.000Z' ],
+	// Nothing about this reading is remarkable in Tokyo; it is the worker zones that make it
+	// worth asserting, since Santiago deletes this local midnight and used to drag the
+	// answer an hour with it.
+	[ '2026-09-06', 'Asia/Tokyo', '2026-09-05T15:00:00.000Z' ],
+	// date-fns reads each field as one to N digits, so an unpadded string must land on the
+	// same instant as its padded twin. A one-digit fraction is 5ms to date-fns, not 500.
+	[ '2026-8-2', 'Asia/Tokyo', '2026-08-01T15:00:00.000Z' ],
+	[ '2026-08-02 9:30', 'Asia/Tokyo', '2026-08-02T00:30:00.000Z' ],
+	[ '2026-08-02T9:30:5.5', 'Asia/Tokyo', '2026-08-02T00:30:05.005Z' ],
+];
+
+// A string carrying its own offset is already an instant, so the zone must not move it.
+const INSTANT_CASES: Array< [ string, string ] > = [
+	[ '2026-08-02T00:00:00Z', '2026-08-02T00:00:00.000Z' ],
+	[ '2026-08-02T00:00:00+05:00', '2026-08-01T19:00:00.000Z' ],
+];
+
+/**
+ * The zone-aware half of `parseAsLocalDate`, run from whatever zone the caller's
+ * environment pins.
+ */
+export const describeZonedParsing = () => {
+	describe( 'parseAsLocalDate with a time zone', () => {
+		test.each( CASES )( 'reads %s in %s', ( dateString, timeZone, expected ) => {
+			expect( parseAsLocalDate( dateString, timeZone ).toISOString() ).toBe( expected );
+		} );
+
+		test.each( INSTANT_CASES )( 'leaves %s where it is', ( dateString, expected ) => {
+			expect( parseAsLocalDate( dateString, 'Asia/Tokyo' ).toISOString() ).toBe( expected );
+		} );
+
+		it( 'falls back to the runtime zone where Intl rejects the zone, and says so', () => {
+			const fallback = parseAsLocalDate( '2026-08-02', 'Not/AZone' );
+
+			expect( fallback.getTime() ).toBe( parseAsLocalDate( '2026-08-02' ).getTime() );
+			expect( console ).toHaveWarnedWith(
+				'[Charts] timeZone "Not/AZone" is not a zone Intl accepts, so dates are read in the browser\'s zone. Pass an IANA name or a UTC offset such as "+05:30".'
+			);
+		} );
+
+		it( 'keeps a year below 100 out of the 1900s', () => {
+			expect( parseAsLocalDate( '0099-08-02', 'Asia/Tokyo' ).getUTCFullYear() ).toBe( 99 );
+			expect( parseAsLocalDate( '99-08-02', 'Asia/Tokyo' ).getUTCFullYear() ).toBe( 99 );
+		} );
+
+		it( 'reads a naive string in the runtime zone when no zone is supplied', () => {
+			const local = parseAsLocalDate( '2026-08-02' );
+
+			expect( [
+				local.getFullYear(),
+				local.getMonth(),
+				local.getDate(),
+				local.getHours(),
+			] ).toEqual( [ 2026, 7, 2, 0 ] );
+		} );
+	} );
+};

package/src/types.ts

@@ -478,8 +478,8 @@ export type BucketInfo = {
  * `timeZone` re-dates the instants the host supplies, so a value that is really a
  * calendar day shifts under it: `new Date( '2026-08-02' )` is UTC midnight and
  * labels as Aug 1 in `America/Los_Angeles`. Supply true instants alongside a
- * `timeZone`, or set only `locale` for day-bucketed data. `HeatmapChart`'s
- * calendar labels take neither — see `buildCalendarHeatmapData`.
+ * `timeZone`, or set only `locale` for day-bucketed data. `buildCalendarHeatmapData`
+ * is the exception: it reads a bare `yyyy-MM-dd` as the day it names.
  */
 export type ChartFormatting = {
 	/** BCP-47 language tag, e.g. `de-DE`. Defaults to the runtime's locale. */

package/src/utils/date-formatting.ts

@@ -1,11 +1,6 @@
+import { warnOnce } from './warn-once';
 import type { ChartFormatting } from '../types';
 
-/**
- * `process.env.NODE_ENV` is replaced by the bundler at build time. Declare a
- * minimal `process` locally so this file type-checks as source under `jetpack:src`.
- */
-declare const process: { env: Record< string, string | undefined > };
-
 // One `Intl.DateTimeFormat` per locale, zone and options triple. The axis formats
 // every bucket in the domain, and rebuilding the formatter is what costs; the tick
 // formats themselves are rebuilt on every resize, so a per-closure cache is not
@@ -27,18 +22,6 @@ const getFormatter = (
 	return formatter;
 };
 
-const warned = new Set< string >();
-
-const warnOnce = ( key: string, message: string ): void => {
-	if ( warned.has( key ) || process.env.NODE_ENV === 'production' ) {
-		return;
-	}
-
-	warned.add( key );
-	// eslint-disable-next-line no-console
-	console.warn( `[Charts] ${ message }` );
-};
-
 const isUsable = ( formatting: ChartFormatting ): boolean => {
 	try {
 		// Constructing is the check: `Intl` throws on a tag or zone it cannot use.