@automattic/charts 4.1.0 → 4.2.0

package/src/components/tooltip/private/bounded-tooltip.tsx

@@ -14,6 +14,9 @@ export type BoundedTooltipProps = Omit< TooltipProps, 'left' | 'top' | 'applyPos
 };
 
 const DEFAULT_OFFSET = 10;
+// Above anything else layered inside a chart, such as the zoom reset button (2).
+// Chart wrappers isolate their stacking context, so it never reaches page chrome.
+export const TOOLTIP_Z_INDEX = 3;
 const POINTER_HEIGHT = 6;
 
 const clamp = ( position: number, min: number, max: number, size: number ) =>
@@ -41,7 +44,8 @@ const findClippingAncestor = ( wrapper: Element ): Element | null => {
 /**
  * Where the box goes, in wrapper coordinates. Automatic placement flips to
  * the side that clips less, then clamps inside `bounds`; below-axis placement
- * is centered on the anchor and clamped horizontally.
+ * is centered on the anchor and clamped horizontally; beside placement preserves
+ * the anchor's y and only flips horizontally before bounds clamping.
  *
  * The flip measures against the visible part of the wrapper, its intersection
  * with `bounds`. Only the clamp is bound by the page: a box that fits inside the
@@ -55,7 +59,7 @@ const findClippingAncestor = ( wrapper: Element ): Element | null => {
  * @param params.offsetTop  - Gap between the anchor and the box, vertically.
  * @param params.box        - Rendered size of the box.
  * @param params.wrapper    - The wrapper's own edges, in wrapper coordinates.
- * @param params.placement  - Fixed below-axis placement or automatic flipping.
+ * @param params.placement  - Below-axis, beside without vertical flipping, or automatic flipping.
  * @param params.bounds     - Edges the box must keep inside, in wrapper coordinates.
  * @return The box's top-left corner; fixed placement preserves the axis's subpixel y.
  */
@@ -103,7 +107,10 @@ export const getBoundedPosition = ( {
 	const upY = top - offsetTop - box.height;
 	const downOverflow = downY + box.height - fit.bottom;
 	const upOverflow = fit.top - upY;
-	let y = downOverflow > 0 && downOverflow > upOverflow ? upY : downY;
+	let y = top;
+	if ( placement !== 'beside' ) {
+		y = downOverflow > 0 && downOverflow > upOverflow ? upY : downY;
+	}
 
 	x = clamp( x, bounds.left, bounds.right, box.width );
 	y = clamp( y, bounds.top, bounds.bottom, box.height );
@@ -122,8 +129,7 @@ export const getBoundedPosition = ( {
  * alone would let the box spill into an `overflow: hidden` card and be cut off.
  *
  * Re-measures on every render, so a box whose content changes width between
- * two hovers is placed for its current size. See `getBoundedPosition` for the
- * below-axis exception.
+ * two hovers is placed for its current size.
  *
  * @param props            - visx `Tooltip` props.
  * @param props.left       - Anchor x, in wrapper coordinates.
@@ -133,7 +139,7 @@ export const getBoundedPosition = ( {
  * @param props.style      - Box styles; visx's defaults unless `unstyled`.
  * @param props.unstyled   - Skip `style` and leave the box bare.
  * @param props.children   - Box content.
- * @param props.placement  - Fixed below-axis placement or automatic flipping.
+ * @param props.placement  - Below-axis, beside without vertical flipping, or automatic flipping.
  * @return The tooltip box.
  */
 export const BoundedTooltip = ( {

package/src/components/tooltip/test/accessible-tooltip.test.tsx

@@ -1,8 +1,10 @@
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import { useRef, useState } from 'react';
 import { LineChartUnresponsive } from '../../../charts/line-chart/line-chart';
 import { GlobalChartsProvider } from '../../../providers';
 import { ChartScopeContext } from '../../../providers/chart-scope';
+import { useKeyboardNavigation } from '../accessible-tooltip';
 import type { ReactNode } from 'react';
 
 // A real chart is the harness rather than the subject: the crosshairs render only once visx has a data context and an open tooltip. The unresponsive export is what lets the test own the scope element — `withResponsive` otherwise provides its own wrapper as the scope.
@@ -86,9 +88,167 @@ describe( 'AccessibleTooltip', () => {
 		}
 	} );
 
+	it.each( [
+		[ 'Tab', '{Tab}' ],
+		[ 'Escape', '{Escape}' ],
+	] )( 'requests scroll suppression when returning focus after %s', async ( _name, keys ) => {
+		const user = userEvent.setup();
+		renderChart( undefined, 'below-axis' );
+		await openTooltip();
+		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		try {
+			await user.keyboard( keys );
+			expect( focus ).toHaveBeenCalledWith( { preventScroll: true } );
+		} finally {
+			focus.mockRestore();
+		}
+	} );
+
+	it.each( [
+		[ 'Tab', '{Tab}' ],
+		[ 'Escape', '{Escape}' ],
+	] )( 'keeps default focus scrolling when returning focus after %s', async ( _name, keys ) => {
+		const user = userEvent.setup();
+		renderChart();
+		await openTooltip();
+		const focus = jest.spyOn( screen.getByRole( 'grid' ), 'focus' );
+		try {
+			await user.keyboard( keys );
+			expect( focus ).toHaveBeenCalledWith();
+		} finally {
+			focus.mockRestore();
+		}
+	} );
+
 	it( 'falls back to the catalog default when the role is unset', async () => {
 		renderChart();
 
 		await expect( openTooltip() ).resolves.toHaveAttribute( 'stroke', '#dbdbdb' );
 	} );
 } );
+
+// Mirrors the charts' markup: the focusable grid wraps the element `chartRef` points at.
+const NavigationHarness = ( { totalPoints }: { totalPoints: number } ) => {
+	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >();
+	const [ isNavigating, setIsNavigating ] = useState( false );
+	const chartRef = useRef< HTMLDivElement >( null );
+	const { onChartKeyDown } = useKeyboardNavigation( {
+		selectedIndex,
+		setSelectedIndex,
+		isNavigating,
+		setIsNavigating,
+		chartRef,
+		totalPoints,
+	} );
+
+	return (
+		<>
+			<div role="grid" aria-label="Harness" tabIndex={ 0 } onKeyDown={ onChartKeyDown }>
+				<div ref={ chartRef } data-testid="selected-index">
+					{ selectedIndex ?? 'none' }
+					<button type="button">Inside</button>
+				</div>
+			</div>
+			<button type="button">Outside</button>
+		</>
+	);
+};
+
+describe( 'useKeyboardNavigation', () => {
+	const navigate = async ( presses: number ) => {
+		const user = userEvent.setup();
+		const view = render( <NavigationHarness totalPoints={ 6 } /> );
+
+		screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+		for ( let i = 0; i < presses; i++ ) {
+			await user.keyboard( '{ArrowRight}' );
+		}
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( String( presses - 1 ) );
+
+		return { user, view };
+	};
+
+	it( 'moves the selection to the last point when the count shrinks while the grid has focus', async () => {
+		const { view } = await navigate( 6 );
+
+		view.rerender( <NavigationHarness totalPoints={ 3 } /> );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( '2' );
+		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+	} );
+
+	// In range rather than past the end: the effect reconciles on any count change, not only an overflow.
+	it( 'clears an in-range selection when the count changes after focus has left the chart', async () => {
+		const { view } = await navigate( 2 );
+
+		screen.getByRole( 'button', { name: 'Outside' } ).focus();
+		view.rerender( <NavigationHarness totalPoints={ 3 } /> );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+	} );
+
+	it( 'returns focus to the grid on Escape when there are no points', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 0 } /> );
+
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		await user.keyboard( '{Escape}' );
+
+		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+	} );
+
+	it( 'returns focus to the grid when the count drops to zero while focus is in the chart', async () => {
+		const { view } = await navigate( 2 );
+
+		screen.getByRole( 'button', { name: 'Inside' } ).focus();
+		view.rerender( <NavigationHarness totalPoints={ 0 } /> );
+
+		expect( screen.getByTestId( 'selected-index' ) ).toHaveTextContent( 'none' );
+		expect( screen.getByRole( 'grid', { name: 'Harness' } ) ).toHaveFocus();
+	} );
+
+	// The page sees the event after the handler, so this is what a surrounding scroll or Modal gets.
+	const recordPageKeyDown = () => {
+		const onKeyDown = jest.fn< void, [ KeyboardEvent ] >();
+		document.addEventListener( 'keydown', onKeyDown );
+		return { onKeyDown, stop: () => document.removeEventListener( 'keydown', onKeyDown ) };
+	};
+
+	it( 'leaves keys it does not handle available to the page', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } /> );
+		const { onKeyDown, stop } = recordPageKeyDown();
+
+		try {
+			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			await user.keyboard( '{ArrowDown}{PageDown}[Space]' );
+
+			expect( onKeyDown ).toHaveBeenCalledTimes( 3 );
+			for ( const [ event ] of onKeyDown.mock.calls ) {
+				expect( event.defaultPrevented ).toBe( false );
+			}
+		} finally {
+			stop();
+		}
+	} );
+
+	// `@wordpress/components` Modal skips its own close-on-Escape once the event is defaultPrevented.
+	it( 'leaves Escape to the page when there is no selection to dismiss', async () => {
+		const user = userEvent.setup();
+		render( <NavigationHarness totalPoints={ 6 } /> );
+		const { onKeyDown, stop } = recordPageKeyDown();
+
+		try {
+			screen.getByRole( 'grid', { name: 'Harness' } ).focus();
+			await user.keyboard( '{Escape}' );
+
+			expect( onKeyDown.mock.calls[ 0 ][ 0 ].defaultPrevented ).toBe( false );
+
+			await user.keyboard( '{ArrowRight}{Escape}' );
+
+			expect( onKeyDown.mock.calls.at( -1 )?.[ 0 ].defaultPrevented ).toBe( true );
+		} finally {
+			stop();
+		}
+	} );
+} );

package/src/components/tooltip/test/bounded-tooltip.test.tsx

@@ -5,6 +5,23 @@ const BOX = { width: 208, height: 36 };
 const OFFSETS = { offsetLeft: 10, offsetTop: 10 };
 
 describe( 'getBoundedPosition', () => {
+	test.each( [
+		[ 40, 50 ],
+		[ 700, 425 ],
+	] )( 'keeps a beside tooltip at its anchor and flips horizontally at %s', ( left, x ) => {
+		expect(
+			getBoundedPosition( {
+				left,
+				top: -20,
+				...OFFSETS,
+				box: { width: 265, height: 382 },
+				wrapper: { left: 0, top: 0, right: 800, bottom: 300 },
+				bounds: { left: 0, top: -100, right: 800, bottom: 500 },
+				placement: 'beside',
+			} )
+		).toEqual( { x, y: -20 } );
+	} );
+
 	test( 'sits below and to the right of the anchor when that fits', () => {
 		expect(
 			getBoundedPosition( {

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

@@ -1,9 +1,9 @@
 import { render, screen, waitFor } from '@testing-library/react';
-import { BarSeries, LineSeries, TooltipContext, XYChart } from '@visx/xychart';
+import { BarSeries, buildChartTheme, LineSeries, TooltipContext, XYChart } from '@visx/xychart';
 import { useContext, useEffect } from 'react';
 import { XyChartTooltip } from '../xy-chart-tooltip';
 import type { XyChartTooltipProps } from '../../../visx/types';
-import type { EventHandlerParams } from '@visx/xychart';
+import type { EventHandlerParams, XYChartTheme } from '@visx/xychart';
 
 type Datum = { x: number; y: number };
 
@@ -76,7 +76,8 @@ const renderChart = (
 	params: EventHandlerParams< Datum >[] = [
 		{ key: 'A', index: 1, datum: SERIES_A[ 1 ], svgPoint: { x: 123, y: 45 } },
 	],
-	margin = NO_MARGIN
+	margin = NO_MARGIN,
+	theme?: XYChartTheme
 ) =>
 	render(
 		<div data-testid="wrapper" style={ { position: 'relative' } }>
@@ -84,6 +85,7 @@ const renderChart = (
 				width={ 200 }
 				height={ 100 }
 				margin={ margin }
+				theme={ theme }
 				xScale={ { type: 'linear', domain: [ 0, 10 ] } }
 				yScale={ { type: 'linear', domain: [ 0, 100 ] } }
 			>
@@ -100,6 +102,23 @@ const renderChart = (
 	);
 
 describe( 'XyChartTooltip', () => {
+	test.each( [
+		[ 'CanvasText', '0 1px 2px #22222255' ],
+		[ '#123456', '0 1px 2px #12345655' ],
+	] )( 'renders a valid shadow for htmlLabel color %s', async ( color, boxShadow ) => {
+		const theme = buildChartTheme( {
+			backgroundColor: '#ffffff',
+			colors: [ '#123456' ],
+			tickLength: 4,
+			gridColor: '#dddddd',
+			gridColorDark: '#222222',
+			htmlLabel: { color },
+		} );
+		renderChart( {}, undefined, undefined, theme );
+
+		await expect( screen.findByTestId( 'tooltip-box' ) ).resolves.toHaveStyle( { boxShadow } );
+	} );
+
 	test( 'renders the tooltip box inside the chart wrapper, not in a body-level portal', async () => {
 		const { container } = renderChart();
 
@@ -120,6 +139,13 @@ describe( 'XyChartTooltip', () => {
 		} );
 	} );
 
+	test( 'pins beside placement to the explicit SVG top anchor', async () => {
+		renderChart( { tooltipPlacement: 'beside', tooltipAnchorTop: 20, snapTooltipToDatumY: true } );
+		await expect( screen.findByTestId( 'tooltip-box' ) ).resolves.toHaveStyle( {
+			transform: 'translate(133px, 20px)',
+		} );
+	} );
+
 	test( 'snaps the box to the nearest datum', async () => {
 		renderChart( { snapTooltipToDatumX: true, snapTooltipToDatumY: true } );
 

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

@@ -2,7 +2,8 @@ import { Tooltip, defaultStyles } from '@visx/tooltip';
 import { DataContext, TooltipContext } from '@visx/xychart';
 import { useCallback, useContext, useState } from 'react';
 import { createPortal } from 'react-dom';
-import { BoundedTooltip } from './private/bounded-tooltip';
+import { isValidHexColor } from '../../utils';
+import { BoundedTooltip, TOOLTIP_Z_INDEX } from './private/bounded-tooltip';
 import type {
 	CrosshairStyle,
 	RenderTooltipGlyphProps,
@@ -35,9 +36,6 @@ const crosshairPaintProps = ( props: CrosshairStyle = {} ) => {
 };
 const DEFAULT_GLYPH_RADIUS = 4;
 const FALLBACK_COLOR = '#222';
-// Above the chart's own overlays (the zoom reset button sits at 2). The chart
-// wrapper isolates its stacking context, so this never competes with page chrome.
-const DEFAULT_TOOLTIP_Z_INDEX = 3;
 // Portal-era options, accepted for compatibility and dropped before the box
 // renders: it sits in the chart wrapper and moves with it, and nothing
 // measures it any more.
@@ -109,7 +107,8 @@ const XyChartTooltipContent = < Datum extends object >( {
 	horizontalCrosshairStyle,
 	detectBounds = true,
 	tooltipPlacement = 'auto',
-	zIndex = DEFAULT_TOOLTIP_Z_INDEX,
+	tooltipAnchorTop,
+	zIndex = TOOLTIP_Z_INDEX,
 	style,
 	...rest
 }: XyChartTooltipContentProps< Datum > ) => {
@@ -170,7 +169,9 @@ const XyChartTooltipContent = < Datum extends object >( {
 		const size = Number( glyphStyle?.radius ?? DEFAULT_GLYPH_RADIUS );
 		const labelColor = theme?.htmlLabel?.color ?? FALLBACK_COLOR;
 		// visx colours a lone nearest-datum glyph like the gridlines and series glyphs like labels.
-		const fallbackColor = showSeriesGlyphs ? labelColor : theme?.gridStyles?.stroke ?? labelColor;
+		const fallbackColor = showSeriesGlyphs
+			? labelColor
+			: ( theme?.gridStyles?.stroke ?? labelColor );
 		let entries: Array< { key: string; datum: Datum; index: number } > = [];
 		if ( showSeriesGlyphs ) {
 			entries = Object.values( tooltipContext.tooltipData?.datumByKey ?? {} );
@@ -213,14 +214,13 @@ const XyChartTooltipContent = < Datum extends object >( {
 	const marginTop = margin?.top ?? 0;
 	const marginLeft = margin?.left ?? 0;
 
-	const TooltipComponent =
-		detectBounds || tooltipPlacement === 'below-axis' ? BoundedTooltip : Tooltip;
+	const TooltipComponent = detectBounds || tooltipPlacement !== 'auto' ? BoundedTooltip : Tooltip;
 	const boxStyle: CSSProperties = {
 		...defaultStyles,
 		zIndex,
 		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,
@@ -264,12 +264,12 @@ const XyChartTooltipContent = < Datum extends object >( {
 						top={
 							tooltipPlacement === 'below-axis'
 								? marginTop + innerHeight + ( margin?.bottom ?? 0 )
-								: tooltipTop
+								: ( tooltipAnchorTop ?? tooltipTop )
 						}
 						style={ boxStyle }
 						applyPositionStyle
 						{ ...tooltipProps }
-						{ ...( tooltipPlacement === 'below-axis' && { placement: tooltipPlacement } ) }
+						{ ...( tooltipPlacement !== 'auto' && { placement: tooltipPlacement } ) }
 					>
 						{ tooltipContent }
 					</TooltipComponent>,

package/src/hooks/test/use-element-size.test.tsx

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { useElementSize } from '../use-element-size';
 
 // Mock ResizeObserver
@@ -66,7 +66,7 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach the element
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 300 );
@@ -84,7 +84,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
@@ -100,7 +100,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 0 );
@@ -129,10 +129,10 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach first element
-		refCallback( mockElement1 as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement1 as unknown as HTMLDivElement ) );
 
 		// Attach second element
-		refCallback( mockElement2 as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement2 as unknown as HTMLDivElement ) );
 
 		expect( disconnectSpy ).toHaveBeenCalled();
 	} );
@@ -155,10 +155,10 @@ describe( 'useElementSize', () => {
 		const [ refCallback ] = result.current;
 
 		// Attach element
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		// Remove element
-		refCallback( null as unknown as HTMLDivElement );
+		act( () => refCallback( null as unknown as HTMLDivElement ) );
 
 		expect( disconnectSpy ).toHaveBeenCalled();
 	} );
@@ -180,7 +180,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		expect( globalThis.ResizeObserver ).toHaveBeenCalled();
 		expect( observeSpy ).toHaveBeenCalledWith( mockElement );
@@ -207,7 +207,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockSpanElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockSpanElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 75 );
@@ -236,7 +236,7 @@ describe( 'useElementSize', () => {
 		const { result } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 100 );
@@ -244,7 +244,7 @@ describe( 'useElementSize', () => {
 		} );
 
 		// Simulate resize
-		resizeCallback();
+		act( () => resizeCallback() );
 
 		await waitFor( () => {
 			expect( result.current[ 1 ] ).toBe( 200 );
@@ -269,7 +269,7 @@ describe( 'useElementSize', () => {
 		const { result, unmount } = renderHook( () => useElementSize() );
 		const [ refCallback ] = result.current;
 
-		refCallback( mockElement as unknown as HTMLDivElement );
+		act( () => refCallback( mockElement as unknown as HTMLDivElement ) );
 		unmount();
 
 		// The observer should be cleaned up when the hook unmounts

package/src/hooks/use-xychart-theme.ts

@@ -23,7 +23,7 @@ export const useXYChartTheme = ( data: SeriesData[] ) => {
 		// One resolver for all three, so they share a single getComputedStyle call.
 		const resolve = createCssVariableResolver( scopeElement );
 		const resolveColor = ( value?: string ): string | undefined =>
-			value ? resolve( value ) ?? value : value;
+			value ? ( resolve( value ) ?? value ) : value;
 
 		const seriesColors: string[] = JSON.parse( seriesColorKey );
 

package/src/index.ts

@@ -10,7 +10,9 @@ export {
 	HeatmapChart,
 	HeatmapChartUnresponsive,
 	buildCalendarHeatmapData,
+	buildMonthCalendarHeatmapData,
 	useCalendarHeatmapData,
+	useMonthCalendarHeatmapData,
 } from './charts/heatmap-chart';
 export { LeaderboardChart, LeaderboardChartUnresponsive } from './charts/leaderboard-chart';
 export { LineChart, LineChartUnresponsive } from './charts/line-chart';
@@ -95,7 +97,7 @@ export type { LegendProps, BaseLegendProps, ChartLegendOptions } from './compone
 
 // Previously available via '@automattic/charts/bar-chart', '@automattic/charts/line-chart', etc.
 export type { AreaChartProps } from './charts/area-chart';
-export type { BarChartProps } from './charts/bar-chart';
+export type { BarChartProps, BandHighlightSelection } from './charts/bar-chart';
 export type {
 	BarListChartProps,
 	RenderLabelProps,
@@ -112,10 +114,14 @@ export type {
 export type {
 	HeatmapChartProps,
 	HeatmapColumn,
+	HeatmapColumnGroup,
 	HeatmapCell,
 	HeatmapTooltipData,
 	CalendarHeatmapOptions,
 	CalendarHeatmapResult,
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
 } from './charts/heatmap-chart';
 export type { LeaderboardChartProps } from './charts/leaderboard-chart';
 export type {

package/src/providers/chart-context/themes.ts

@@ -61,6 +61,7 @@ const defaultTheme: CompleteChartTheme = {
 	heatmapChart: {
 		compactCellGap: 2,
 		compactCellSize: 11,
+		groupGap: 24,
 	},
 };
 

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
@@ -100,7 +101,7 @@ function parseTokensDoc(): Map< string, Entry > {
 		const token = /(--wp[\w-]+)/.exec( mapping );
 
 		entries.set( role, {
-			reads: unmapped ? null : derives?.[ 1 ] ?? token?.[ 1 ] ?? null,
+			reads: unmapped ? null : ( derives?.[ 1 ] ?? token?.[ 1 ] ?? null ),
 			fallback: fallback === '—' ? null : normalize( fallback ),
 		} );
 	}
@@ -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() );
 	} );