@automattic/charts 4.1.1 → 4.2.0

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.
@@ -124,3 +126,129 @@ describe( 'AccessibleTooltip', () => {
 		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

@@ -139,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

@@ -3,7 +3,7 @@ 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 { BoundedTooltip, TOOLTIP_Z_INDEX } from './private/bounded-tooltip';
 import type {
 	CrosshairStyle,
 	RenderTooltipGlyphProps,
@@ -36,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.
@@ -110,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 > ) => {
@@ -171,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 ?? {} );
@@ -214,8 +214,7 @@ 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,
@@ -265,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/test/chart-scope.test.ts

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

package/src/types.ts

@@ -53,12 +53,7 @@ export type LegendShape< Data, Output > =
 	| ComponentClass< LegendShapeRenderProps< Data, Output > >;
 
 export type GoogleDataTableColumnType =
-	| 'string'
-	| 'number'
-	| 'boolean'
-	| 'date'
-	| 'datetime'
-	| 'timeofday';
+	'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'timeofday';
 
 export enum GoogleDataTableColumnRoleType {
 	annotation = 'annotation',
@@ -98,13 +93,7 @@ export type GoogleDataTableCell =
 export type GoogleDataTableRow = GoogleDataTableCell[];
 
 export type ChartType =
-	| 'area'
-	| 'bar'
-	| 'conversion-funnel'
-	| 'leaderboard'
-	| 'line'
-	| 'pie'
-	| 'pie-semi-circle';
+	'area' | 'bar' | 'conversion-funnel' | 'leaderboard' | 'line' | 'pie' | 'pie-semi-circle';
 
 export type OrientationType = ValueOf< typeof Orientation >;
 
@@ -145,6 +134,7 @@ export type ThemeAnnotationStyles = {
 export type DataPoint = {
 	label: string;
 	value: number;
+	color?: string;
 };
 
 /**
@@ -196,6 +186,7 @@ export type DataPointDate = {
 	dateString?: string;
 	value: number | null;
 	label?: string;
+	color?: string;
 };
 
 export type LeaderboardEntry = {
@@ -424,6 +415,8 @@ export type ChartTheme = {
 		compactCellGap?: number;
 		/** Fixed square cell size in px for compact mode */
 		compactCellSize?: number;
+		/** Gap in px between adjacent column groups; in compact mode the minimum, as the gaps share leftover width */
+		groupGap?: number;
 	};
 };
 

package/src/utils/format-metric-value.ts

@@ -47,13 +47,13 @@ export const formatMetricValue = (
 							maximumFractionDigits: decimals ?? 2,
 							signDisplay,
 						},
-				  } )
+					} )
 				: formatNumber( numericValue, {
 						decimals: decimals ?? 2,
 						numberFormatOptions: {
 							signDisplay,
 						},
-				  } );
+					} );
 			return `$${ formatted }`;
 		}
 
@@ -80,13 +80,13 @@ export const formatMetricValue = (
 							maximumFractionDigits: decimals ?? 0,
 							signDisplay,
 						},
-				  } )
+					} )
 				: formatNumber( numericValue, {
 						decimals: decimals ?? 0,
 						numberFormatOptions: {
 							signDisplay,
 						},
-				  } );
+					} );
 		}
 	}
 };

package/src/utils/get-edge-tick-widths.ts

@@ -24,7 +24,7 @@ export const getEdgeTickWidths = < T extends AnyD3Scale >(
 
 	const lastIndex = ticks.length - 1;
 	const label = ( tick: ScaleInput< T >, index: number ) =>
-		String( formatTick ? formatTick( tick, index, [] ) ?? '' : tick );
+		String( formatTick ? ( formatTick( tick, index, [] ) ?? '' ) : tick );
 
 	return {
 		first: getStringWidth( label( ticks[ 0 ], 0 ), labelStyle ) ?? 0,

package/src/utils/get-styles.ts

@@ -103,7 +103,7 @@ export function getItemShapeStyles(
 	const hasExplicitStyles = Object.values( explicitStyles ).some(
 		value => value !== undefined && value !== null && value !== ''
 	);
-	const baseShapeStyles = hasExplicitStyles ? explicitStyles : themeShapeStyles ?? {};
+	const baseShapeStyles = hasExplicitStyles ? explicitStyles : ( themeShapeStyles ?? {} );
 
 	// Layer the comparison bar opacity on top so the swatch matches the translucent bar
 	// without discarding the base (custom or theme) shape styles.

package/src/visx/types.ts

@@ -12,15 +12,10 @@ export interface RenderTooltipGlyphProps< Datum extends object > extends GlyphPr
 	isNearestDatum: boolean;
 }
 
-export type TooltipPlacement = 'auto' | 'below-axis';
+export type TooltipPlacement = 'auto' | 'below-axis' | 'beside';
 
 type CrosshairPaintProperty =
-	| 'stroke'
-	| 'strokeWidth'
-	| 'strokeOpacity'
-	| 'strokeDasharray'
-	| 'strokeLinecap'
-	| 'opacity';
+	'stroke' | 'strokeWidth' | 'strokeOpacity' | 'strokeDasharray' | 'strokeLinecap' | 'opacity';
 
 export type CrosshairStyle = Pick< SVGProps< SVGLineElement >, CrosshairPaintProperty > & {
 	className?: string;
@@ -31,11 +26,13 @@ export type XyChartTooltipProps< Datum extends object > = {
 	renderTooltip: ( params: RenderTooltipParams< Datum > ) => ReactNode;
 	renderGlyph?: ( params: RenderTooltipGlyphProps< Datum > ) => ReactNode;
 	/**
-	 * Keep the panel below the x-axis label band, centered at the datum x and horizontally clamped.
-	 * Vertical bounds do not move this placement; clipping ancestors can still cut it off.
+	 * Use below-axis placement for centered axis anchoring, or beside placement to avoid vertical flipping.
+	 * Below-axis ignores vertical bounds; beside placement clamps to them.
 	 * @default 'auto'
 	 */
 	tooltipPlacement?: TooltipPlacement;
+	/** Override the tooltip top anchor in SVG coordinates, including negative offsets. */
+	tooltipAnchorTop?: number;
 	/** Merge overrides with the default box styles; use `unstyled` to strip the box styling. */
 	style?: VisxTooltipProps[ 'style' ];
 	snapTooltipToDatumX?: boolean;
@@ -52,7 +49,7 @@ export type XyChartTooltipProps< Datum extends object > = {
 	 * that clips its overflow, or the viewport when there is none. The box may
 	 * leave the chart wrapper. (It used to keep a body-level portal inside the
 	 * viewport.)
-	 * Ignored by `below-axis`.
+	 * Non-auto placements always apply their own bounds handling.
 	 * @default true
 	 */
 	detectBounds?: boolean;