@automattic/charts 4.0.0 → 4.1.1

package/src/components/tooltip/xy-chart-tooltip.tsx

@@ -2,12 +2,38 @@ import { Tooltip, defaultStyles } from '@visx/tooltip';
 import { DataContext, TooltipContext } from '@visx/xychart';
 import { useCallback, useContext, useState } from 'react';
 import { createPortal } from 'react-dom';
+import { isValidHexColor } from '../../utils';
 import { BoundedTooltip } from './private/bounded-tooltip';
-import type { RenderTooltipGlyphProps, XyChartTooltipProps } from '../../visx/types';
+import type {
+	CrosshairStyle,
+	RenderTooltipGlyphProps,
+	XyChartTooltipProps,
+} from '../../visx/types';
 import type { TooltipContextType } from '@visx/xychart';
 import type { CSSProperties, ReactNode } from 'react';
 
 const CROSSHAIR_STROKE_WIDTH = 1.5;
+const CROSSHAIR_PAINT_PROPERTIES = new Set( [
+	'stroke',
+	'strokeWidth',
+	'strokeOpacity',
+	'strokeDasharray',
+	'strokeLinecap',
+	'opacity',
+] );
+
+const crosshairPaintProps = ( props: CrosshairStyle = {} ) => {
+	const pickPaint = ( value: object ) =>
+		Object.fromEntries(
+			Object.entries( value ).filter( ( [ key ] ) => CROSSHAIR_PAINT_PROPERTIES.has( key ) )
+		);
+
+	return {
+		...pickPaint( props ),
+		...( props.className === undefined ? {} : { className: props.className } ),
+		...( props.style === undefined ? {} : { style: pickPaint( props.style ) } ),
+	};
+};
 const DEFAULT_GLYPH_RADIUS = 4;
 const FALLBACK_COLOR = '#222';
 // Above the chart's own overlays (the zoom reset button sits at 2). The chart
@@ -83,7 +109,9 @@ const XyChartTooltipContent = < Datum extends object >( {
 	verticalCrosshairStyle,
 	horizontalCrosshairStyle,
 	detectBounds = true,
+	tooltipPlacement = 'auto',
 	zIndex = DEFAULT_TOOLTIP_Z_INDEX,
+	style,
 	...rest
 }: XyChartTooltipContentProps< Datum > ) => {
 	const tooltipProps = Object.fromEntries(
@@ -125,9 +153,12 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const nearestDatum = tooltipContext.tooltipData?.nearestDatum;
 	let { tooltipLeft, tooltipTop } = tooltipContext;
 
-	if ( nearestDatum && ( snapTooltipToDatumX || snapTooltipToDatumY ) ) {
+	if (
+		nearestDatum &&
+		( snapTooltipToDatumX || snapTooltipToDatumY || tooltipPlacement === 'below-axis' )
+	) {
 		const { left, top } = getDatumLeftTop( nearestDatum.key, nearestDatum.datum );
-		if ( snapTooltipToDatumX && isValidNumber( left ) ) {
+		if ( ( snapTooltipToDatumX || tooltipPlacement === 'below-axis' ) && isValidNumber( left ) ) {
 			tooltipLeft = left;
 		}
 		if ( snapTooltipToDatumY && isValidNumber( top ) ) {
@@ -183,15 +214,17 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const marginTop = margin?.top ?? 0;
 	const marginLeft = margin?.left ?? 0;
 
-	const TooltipComponent = detectBounds ? BoundedTooltip : Tooltip;
+	const TooltipComponent =
+		detectBounds || tooltipPlacement === 'below-axis' ? BoundedTooltip : Tooltip;
 	const boxStyle: CSSProperties = {
 		...defaultStyles,
 		zIndex,
-		background: theme?.backgroundColor ?? 'white',
+		backgroundColor: theme?.backgroundColor ?? 'white',
 		boxShadow: `0 1px 2px ${
-			theme?.htmlLabel?.color ? `${ theme.htmlLabel.color }55` : '#22222255'
+			isValidHexColor( theme?.htmlLabel?.color ) ? `${ theme.htmlLabel.color }55` : '#22222255'
 		}`,
 		...theme?.htmlLabel,
+		...style,
 	};
 
 	return (
@@ -201,26 +234,26 @@ const XyChartTooltipContent = < Datum extends object >( {
 					<line
 						className="visx-crosshair visx-crosshair-vertical"
 						data-testid="xy-chart-tooltip-crosshair-vertical"
+						stroke={ crosshairStroke }
+						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
+						{ ...crosshairPaintProps( verticalCrosshairStyle ) }
 						x1={ tooltipLeft }
 						x2={ tooltipLeft }
 						y1={ marginTop }
 						y2={ marginTop + innerHeight }
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...verticalCrosshairStyle }
 					/>
 				) }
 				{ showHorizontalCrosshair && isValidNumber( tooltipTop ) && (
 					<line
 						className="visx-crosshair visx-crosshair-horizontal"
 						data-testid="xy-chart-tooltip-crosshair-horizontal"
+						stroke={ crosshairStroke }
+						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
+						{ ...crosshairPaintProps( horizontalCrosshairStyle ) }
 						x1={ marginLeft }
 						x2={ marginLeft + innerWidth }
 						y1={ tooltipTop }
 						y2={ tooltipTop }
-						stroke={ crosshairStroke }
-						strokeWidth={ CROSSHAIR_STROKE_WIDTH }
-						{ ...horizontalCrosshairStyle }
 					/>
 				) }
 				{ glyphs }
@@ -229,10 +262,15 @@ const XyChartTooltipContent = < Datum extends object >( {
 				createPortal(
 					<TooltipComponent
 						left={ tooltipLeft }
-						top={ tooltipTop }
+						top={
+							tooltipPlacement === 'below-axis'
+								? marginTop + innerHeight + ( margin?.bottom ?? 0 )
+								: tooltipTop
+						}
 						style={ boxStyle }
 						applyPositionStyle
 						{ ...tooltipProps }
+						{ ...( tooltipPlacement === 'below-axis' && { placement: tooltipPlacement } ) }
 					>
 						{ tooltipContent }
 					</TooltipComponent>,
@@ -259,7 +297,8 @@ const XyChartTooltipContent = < Datum extends object >( {
  * isolation keeps the box's `zIndex` from competing with page chrome. The box
  * flips and clamps to stay inside the nearest ancestor that clips its overflow
  * (or the viewport), so it may extend past the chart wrapper but is never cut
- * off unless that ancestor is smaller than the box itself.
+ * off unless that ancestor is smaller than the box itself. Below-axis placement
+ * pins it beneath the x-axis and applies horizontal bounds only.
  *
  * @param props - visx's `Tooltip` options. `scroll`, `debounce` and `resizeObserverPolyfill` are accepted and ignored.
  * @return An anchor in the SVG, plus the overlay and the tooltip box while the tooltip is open.

package/src/hooks/test/use-chart-data-transform-zone.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { GlobalChartsProvider } from '../../providers';
+import { useChartDataTransform } from '../use-chart-data-transform';
+import type { SeriesData } from '../../types';
+
+// One reference, reused across both renders, so only the zone can invalidate the memo.
+const data: SeriesData[] = [
+	{ label: 'Series A', data: [ { dateString: '2026-08-02', value: 1 } ] },
+];
+
+const Probe = () => {
+	const [ series ] = useChartDataTransform( data );
+	const point = series.data[ 0 ] as { date?: Date };
+
+	return <span data-testid="instant">{ point.date?.toISOString() }</span>;
+};
+
+describe( 'useChartDataTransform', () => {
+	it( 're-dates its points when only the provider time zone changes', () => {
+		const { rerender } = render(
+			<GlobalChartsProvider timeZone="Asia/Tokyo">
+				<Probe />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByTestId( 'instant' ) ).toHaveTextContent( '2026-08-01T15:00:00.000Z' );
+
+		rerender(
+			<GlobalChartsProvider timeZone="Pacific/Auckland">
+				<Probe />
+			</GlobalChartsProvider>
+		);
+
+		expect( screen.getByTestId( 'instant' ) ).toHaveTextContent( '2026-08-01T12:00:00.000Z' );
+	} );
+} );

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/styles/chart-scope.scss

@@ -42,9 +42,7 @@
 	// The literal is load-bearing: a `fill` reading a fallback-less var() on an
 	// undeclared property drops the declaration and paints black instead.
 	--a8c-charts-color-label-background: transparent;
-	// The SVG axis and tick labels. Narrower than --a8c-charts-color-label and
-	// derived from it, so setting the broad role moves every label at once while
-	// setting this one moves only the axis.
+	// See TOKENS.md's "Broad roles and narrow ones" for label inheritance.
 	--a8c-charts-color-label-axis: var(--a8c-charts-color-label);
 	--a8c-charts-color-annotation: var(--wpds-color-foreground-content-neutral);
 	--a8c-charts-color-trend-up: var(--wpds-color-foreground-content-success-weak);
@@ -86,3 +84,13 @@
 	--a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md);
 	--a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs);
 }
+
+@media (forced-colors: active) {
+
+	:where(.a8c-charts-scope) {
+		--a8c-charts-color-label-axis: CanvasText;
+		--a8c-charts-color-grid: GrayText;
+		--a8c-charts-color-axis-x: GrayText;
+		--a8c-charts-color-tick-x: GrayText;
+	}
+}

package/src/styles/test/chart-scope.test.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { compileString } from 'sass-embedded';
 
 const stylesheet = readFileSync( join( __dirname, '..', 'chart-scope.scss' ), 'utf8' );
 const tokensDoc = readFileSync( join( __dirname, '..', '..', '..', 'TOKENS.md' ), 'utf8' );
@@ -19,7 +20,7 @@ type Entry = {
  * @return Every declared `--a8c-charts-*` property, keyed by name.
  */
 function parseStylesheet(): Map< string, Entry > {
-	const body = stylesheet.slice( stylesheet.indexOf( '{' ) + 1, stylesheet.lastIndexOf( '}' ) );
+	const body = stylesheet.slice( stylesheet.indexOf( '{' ) + 1, stylesheet.indexOf( '}' ) );
 	const entries = new Map< string, Entry >();
 
 	for ( const declaration of body
@@ -112,6 +113,39 @@ const declared = parseStylesheet();
 const documented = parseTokensDoc();
 
 describe( 'chart scope catalog', () => {
+	it( 'uses system colors for axis text and visible lines only under forced colors', () => {
+		const style = document.createElement( 'style' );
+		style.textContent = compileString( stylesheet ).css;
+		document.head.appendChild( style );
+
+		try {
+			const mediaRules = Array.from( style.sheet!.cssRules ).filter(
+				( rule ): rule is CSSMediaRule => rule.type === CSSRule.MEDIA_RULE
+			);
+			expect( mediaRules ).toHaveLength( 1 );
+			expect( mediaRules[ 0 ].conditionText ).toBe( '(forced-colors: active)' );
+			expect( mediaRules[ 0 ].cssRules ).toHaveLength( 1 );
+
+			const rule = mediaRules[ 0 ].cssRules[ 0 ] as CSSStyleRule;
+			expect( rule.selectorText ).toBe( ':where(.a8c-charts-scope)' );
+			expect(
+				Object.fromEntries(
+					Array.from( rule.style ).map( property => [
+						property,
+						rule.style.getPropertyValue( property ).trim().toLowerCase(),
+					] )
+				)
+			).toEqual( {
+				'--a8c-charts-color-label-axis': 'canvastext',
+				'--a8c-charts-color-grid': 'graytext',
+				'--a8c-charts-color-axis-x': 'graytext',
+				'--a8c-charts-color-tick-x': 'graytext',
+			} );
+		} finally {
+			style.remove();
+		}
+	} );
+
 	it( 'documents every declared role, and declares every documented one', () => {
 		expect( [ ...documented.keys() ].sort() ).toEqual( [ ...declared.keys() ].sort() );
 	} );