@automattic/charts 4.1.1 → 4.2.0

package/src/charts/heatmap-chart/types.ts

@@ -1,5 +1,5 @@
 import type { BaseChartProps } from '../../types';
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 
 /** A single heatmap cell. `value: null` marks an empty cell. */
 export type HeatmapCell = {
@@ -36,19 +36,46 @@ export type HeatmapColumn = {
 	summary?: boolean;
 };
 
+/** A run of consecutive columns sharing one label beneath the grid. */
+export type HeatmapColumnGroup = {
+	label: string;
+	/** Columns covered; a positive integer. */
+	span: number;
+};
+
 export type HeatmapTooltipData = {
 	value: number | null;
 	rowLabel?: string;
 	columnLabel?: string;
+	/** Label of the column group the cell falls in, if any. */
+	groupLabel?: string;
 	cellLabel?: string;
 	row: number;
 	column: number;
 };
 
-export interface HeatmapChartProps
-	extends Omit< BaseChartProps< HeatmapColumn[] >, 'showLegend' | 'legend' | 'gridVisibility' > {
+export interface HeatmapChartProps extends Omit<
+	BaseChartProps< HeatmapColumn[] >,
+	'showLegend' | 'legend' | 'gridVisibility'
+> {
 	/** y-axis labels by row index. Empty entries render blank. */
 	rowLabels?: string[];
+	/**
+	 * Consecutive runs of columns sharing one label beneath the grid, set one
+	 * group gap apart. Runs from the first column; columns past the last group
+	 * stay ungrouped. Ignored, with a warning, when a span is not a positive
+	 * integer or the spans reach past the last column.
+	 */
+	columnGroups?: HeatmapColumnGroup[];
+	/**
+	 * How the arrow keys move the selection. `grid` steps across the whole grid.
+	 * `calendar` reads each column group as a page: Left/Right by one cell (wrapping
+	 * to the next row, then the next group), Up/Down by one row into the neighboring
+	 * group past the edge, Page Up/Down by one group. Default `grid`.
+	 */
+	keyboardNavigation?: 'grid' | 'calendar';
+	/** Accessible name of the grid. Defaults to a localized "Heatmap chart". */
+	ariaLabel?: string;
 	/** Compact mode: hide in-cell values, tighten gap, thin axis labels. Default false. */
 	compact?: boolean;
 	/** Render the numeric value inside each cell. Default `! compact`. */
@@ -80,6 +107,14 @@ export interface HeatmapChartProps
 	 */
 	primaryColor?: string;
 	renderTooltip?: ( data: HeatmapTooltipData ) => ReactNode;
+	/**
+	 * The tooltip box: `light` is the plain white box, `dark` the package's
+	 * tooltip surface, themed through `--a8c-charts-color-tooltip-surface`.
+	 * Default `light`.
+	 */
+	tooltipVariant?: 'light' | 'dark';
+	/** Inline styles merged onto the tooltip box, over the variant's own. */
+	tooltipStyle?: CSSProperties;
 	children?: ReactNode;
 }
 
@@ -111,3 +146,24 @@ export type CalendarHeatmapOptions = {
 	 */
 	timeZone?: string;
 };
+
+export type MonthCalendarHeatmapRange = {
+	/** First measured day, `yyyy-MM-dd`. */
+	start: string;
+	/** Last measured day, `yyyy-MM-dd`, inclusive. */
+	end: string;
+};
+
+export type MonthCalendarHeatmapOptions = {
+	/** 0 = Sunday, 1 = Monday. Default 1. */
+	weekStartsOn?: 0 | 1;
+	/** BCP-47 tag the month and day labels are written in. Defaults to the runtime's locale. */
+	locale?: string;
+};
+
+export type MonthCalendarHeatmapResult = {
+	/** For `HeatmapChart`'s `data`: 7 columns per month, 6 cells each. */
+	data: HeatmapColumn[];
+	/** For `HeatmapChart`'s `columnGroups`: one per month, in order. */
+	columnGroups: HeatmapColumnGroup[];
+};

package/src/charts/heatmap-chart/use-month-calendar-heatmap-data.ts

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+import { useChartFormatting } from '../../providers';
+import { buildMonthCalendarHeatmapData } from './build-month-calendar-data';
+import type {
+	MonthCalendarHeatmapOptions,
+	MonthCalendarHeatmapRange,
+	MonthCalendarHeatmapResult,
+} from './types';
+
+/**
+ * `buildMonthCalendarHeatmapData` with the locale taken from `GlobalChartsProvider`
+ * where the caller names none.
+ *
+ * @param valueByDay - Value per `yyyy-MM-dd`. Held by reference, so a caller that rebuilds it each render defeats the memo.
+ * @param range      - As for `buildMonthCalendarHeatmapData`.
+ * @param options    - As for `buildMonthCalendarHeatmapData`; `locale` wins over the provider.
+ * @return Columns and groups for `HeatmapChart`.
+ */
+export const useMonthCalendarHeatmapData = (
+	valueByDay: Record< string, number | null >,
+	range: MonthCalendarHeatmapRange,
+	options: MonthCalendarHeatmapOptions = {}
+): MonthCalendarHeatmapResult => {
+	const formatting = useChartFormatting();
+	const locale = options.locale ?? formatting.locale;
+	const { weekStartsOn } = options;
+	const { start, end } = range;
+
+	// Spread into primitives: the option and range objects are rebuilt on each render.
+	return useMemo(
+		() => buildMonthCalendarHeatmapData( valueByDay, { start, end }, { locale, weekStartsOn } ),
+		[ valueByDay, start, end, locale, weekStartsOn ]
+	);
+};

package/src/charts/leaderboard-chart/types.ts

@@ -1,20 +1,19 @@
 import { type ReactNode } from 'react';
 import { BaseChartProps, LeaderboardEntry } from '../../types';
 
-export interface LeaderboardChartProps
-	extends Pick<
-		BaseChartProps< LeaderboardEntry >,
-		| 'className'
-		| 'data'
-		| 'showLegend'
-		| 'legend'
-		| 'chartId'
-		| 'width'
-		| 'height'
-		| 'size'
-		| 'gap'
-		| 'animation'
-	> {
+export interface LeaderboardChartProps extends Pick<
+	BaseChartProps< LeaderboardEntry >,
+	| 'className'
+	| 'data'
+	| 'showLegend'
+	| 'legend'
+	| 'chartId'
+	| 'width'
+	| 'height'
+	| 'size'
+	| 'gap'
+	| 'animation'
+> {
 	/**
 	 * Whether to show comparison data
 	 */

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

@@ -505,7 +505,7 @@ const LineChartInternal = forwardRef< ChartInstanceRef, LineChartProps >(
 								background: tooltipStyle?.background,
 								backgroundColor: tooltipStyle?.backgroundColor,
 							}
-					  )
+						)
 					: renderTooltip( { ...params, bucketInfo } ),
 			[ renderTooltip, bucketInfo, tooltipStyle ]
 		);

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

@@ -269,7 +269,7 @@ const LineChartAnnotation: FC< LineChartAnnotationProps > = ( {
 					}px)`,
 					width: labelWidth,
 					height: labelHeight,
-			  }
+				}
 			: undefined;
 	};
 

package/src/charts/line-chart/types.ts

@@ -8,7 +8,7 @@ import type {
 	AnnotationStyles,
 	DataPoint,
 } from '../../types';
-import type { CrosshairStyle, RenderTooltipParams, XyChartTooltipProps } from '../../visx/types';
+import type { CrosshairStyle, RenderTooltipParams } from '../../visx/types';
 import type { GlyphProps } from '@visx/xychart';
 import type { ReactNode, SVGProps, FC, CSSProperties } from 'react';
 
@@ -45,7 +45,7 @@ export interface LineChartProps extends BaseChartProps< SeriesData[] >, SeriesVi
 	 * Place the panel below the x-axis tick labels with a pointer at the datum x; horizontal bounds still apply.
 	 * @default 'auto'
 	 */
-	tooltipPlacement?: XyChartTooltipProps< DataPointDate >[ 'tooltipPlacement' ];
+	tooltipPlacement?: 'auto' | 'below-axis';
 	/**
 	 * Inline container styles; see Below-Axis Tooltips in stories/index.docs.mdx for content color overrides.
 	 */

package/src/charts/private/time-axis-options.ts

@@ -83,7 +83,7 @@ export const buildTimeAxisOptions = ( {
 					effectiveDomain,
 					ownFormatter,
 					callerNumTicks ?? getMaxTicksForWidth( width )
-			  );
+				);
 
 	// An empty selection means the domain holds no point to tick, not that the
 	// axis wants no ticks: visx reads `[]` as the latter and labels nothing.

package/src/charts/private/with-responsive/with-responsive.tsx

@@ -94,7 +94,7 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 		// Cap the available width at maxWidth unless an explicit width pins it. Before
 		// measurement resolves, fall back to the explicit width.
 		const cap = width === undefined ? maxWidth : Infinity;
-		const availableWidth = parentWidth > 0 ? Math.min( parentWidth, cap ) : width ?? 0;
+		const availableWidth = parentWidth > 0 ? Math.min( parentWidth, cap ) : ( width ?? 0 );
 
 		let boxWidth = availableWidth;
 		let boxHeight: number;
@@ -107,7 +107,7 @@ export function withResponsive< T extends Exclude< BaseChartProps< unknown >, 'o
 				boxHeight = derivedHeight;
 			}
 		} else {
-			boxHeight = parentHeight > 0 ? parentHeight : height ?? 0;
+			boxHeight = parentHeight > 0 ? parentHeight : ( height ?? 0 );
 		}
 
 		// Decide containment from the wrapper's real height, measured after layout.

package/src/charts/private/x-zoom/test/x-zoom.test.tsx

@@ -130,9 +130,7 @@ describe( 'useXZoom', () => {
 	} );
 
 	test( 'leaves domain null when the X scale has no invert function', () => {
-		const chartRef = makeChartRef( {
-			/* no invert */
-		} );
+		const chartRef = makeChartRef( { /* no invert */ } );
 		const { result } = renderHook( () => useXZoom< number >( { enabled: true, chartRef } ) );
 
 		act( () => result.current.handlers.onPointerDown( makeParams( 100 ) ) );

package/src/charts/private/x-zoom/x-zoom.tsx

@@ -79,8 +79,7 @@ export function useXZoom< T extends Date | number = Date >( {
 			const hi = Math.max( finalDrag.a, finalDrag.b );
 			if ( hi - lo < MIN_DRAG_PIXELS ) return;
 			const xScale = chartRef.current?.getScales()?.xScale as
-				| ( AxisScale & { invert?: ( v: number ) => T } )
-				| undefined;
+				( AxisScale & { invert?: ( v: number ) => T } ) | undefined;
 			if ( ! xScale || typeof xScale.invert !== 'function' ) return;
 			setDomain( [ xScale.invert( lo ), xScale.invert( hi ) ] );
 		},

package/src/components/legend/private/base-legend.tsx

@@ -75,7 +75,7 @@ const getLegendItemAriaLabel = (
 					_x( '%1$s, %2$s', 'legend item label and value', 'jetpack-charts' ),
 					text,
 					String( value )
-			  )
+				)
 			: text;
 
 	if ( interactive ) {

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

@@ -1,6 +1,8 @@
 import { TooltipContext } from '@visx/xychart';
 import clsx from 'clsx';
 import { useContext, useEffect, useCallback, useMemo, useRef } from 'react';
+import { ChartInstanceContext } from '../../charts/private/chart-instance-context';
+import { useGlobalChartsContext } from '../../providers/chart-context/hooks/use-global-charts-context';
 import { CATALOG_POINTERS } from '../../providers/chart-context/private/catalog-pointers';
 import { useChartScopeElement, useStandaloneScopeClass } from '../../providers/chart-scope';
 import { resolveCssVariable } from '../../utils';
@@ -18,8 +20,10 @@ export type FlattenedTooltipData = {
 };
 
 // Enhanced tooltip with keyboard navigation and accessibility
-interface AccessibleTooltipProps
-	extends Omit< XyChartTooltipProps< DataPointDate >, 'renderTooltip' > {
+interface AccessibleTooltipProps extends Omit<
+	XyChartTooltipProps< DataPointDate >,
+	'renderTooltip'
+> {
 	renderTooltip?: ( params: RenderTooltipParams< DataPointDate > ) => ReactNode;
 	selectedIndex?: number | undefined;
 	tooltipRef?: ( element: HTMLDivElement | null ) => void;
@@ -98,6 +102,40 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 	// Tracks whether this effect opened a tooltip, so it only closes its own.
 	const hasKeyboardSelection = useRef( false );
 
+	// visx's own `hideTooltip` is debounced by 400ms, long enough for a stale datum to be
+	// repainted against a changed series list. This is the undebounced close it wraps.
+	const closeTooltipNow = useCallback( () => {
+		tooltipContext?.updateTooltip( {
+			tooltipOpen: false,
+			tooltipLeft: undefined,
+			tooltipTop: undefined,
+			tooltipData: undefined,
+		} );
+		// Don't include tooltipContext in the dependency array to avoid loop.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [] );
+
+	const chartId = useContext( ChartInstanceContext )?.chartId;
+	const { getHiddenSeries } = useGlobalChartsContext();
+	const hiddenSeriesKey = chartId
+		? JSON.stringify( [ ...getHiddenSeries( chartId ) ].sort() )
+		: undefined;
+	const lastHiddenSeriesKey = useRef( hiddenSeriesKey );
+
+	// Hiding a series re-points every tooltip index at a different series, so a tooltip opened by
+	// the pointer would keep showing a datum that is no longer on the chart. Nothing else closes
+	// it: the pointer has not moved, so visx never fires the leave that would.
+	useEffect( () => {
+		const changed = lastHiddenSeriesKey.current !== hiddenSeriesKey;
+		lastHiddenSeriesKey.current = hiddenSeriesKey;
+
+		// A keyboard selection is reconciled by `useKeyboardNavigation` instead, which either
+		// re-shows the tooltip at a valid index or clears the selection for the branch below.
+		if ( changed && selectedIndex === undefined ) {
+			closeTooltipNow();
+		}
+	}, [ hiddenSeriesKey, selectedIndex, closeTooltipNow ] );
+
 	// Handle tooltip highlighting for keyboard navigation
 	useEffect( () => {
 		if ( selectedIndex === undefined ) {
@@ -106,7 +144,7 @@ export const AccessibleTooltip: React.FC< AccessibleTooltipProps > = ( {
 			// mid-navigation and closes the tooltip the user is reading.
 			if ( hasKeyboardSelection.current ) {
 				hasKeyboardSelection.current = false;
-				tooltipContext?.hideTooltip();
+				closeTooltipNow();
 			}
 			return;
 		}
@@ -201,6 +239,12 @@ interface UseKeyboardNavigationProps {
 	 */
 	onActivate?: ( index: number ) => void;
 	preventTooltipScroll?: boolean;
+	/**
+	 * Identity of the series the navigation indexes run over, for charts whose index space depends
+	 * on which series are visible. Swapping one hidden series for another of the same length leaves
+	 * `totalPoints` unchanged, so the count alone cannot detect it.
+	 */
+	visibleSeriesKey?: string;
 }
 
 export const useKeyboardNavigation = ( {
@@ -212,21 +256,78 @@ export const useKeyboardNavigation = ( {
 	totalPoints,
 	onActivate,
 	preventTooltipScroll = false,
+	visibleSeriesKey,
 }: UseKeyboardNavigationProps ) => {
+	// `chartRef` sits inside the focusable grid, so the grid is what focus returns to and is measured against.
+	const getChartRoot = useCallback(
+		(): HTMLElement | null =>
+			chartRef.current?.closest< HTMLElement >( '[role="grid"]' ) ?? chartRef.current,
+		[ chartRef ]
+	);
+
+	const focusWithoutScrollIfNeeded = useCallback(
+		( element: HTMLElement | null | undefined ) => {
+			if ( preventTooltipScroll ) {
+				element?.focus( { preventScroll: true } );
+			} else {
+				element?.focus();
+			}
+		},
+		[ preventTooltipScroll ]
+	);
+
 	// Focus the tooltip as soon as it is rendered
 	const tooltipRef = useCallback(
 		( element: HTMLDivElement | null ) => {
 			if ( element && selectedIndex !== undefined ) {
-				if ( preventTooltipScroll ) {
-					element.focus( { preventScroll: true } );
-				} else {
-					element.focus();
-				}
+				focusWithoutScrollIfNeeded( element );
 			}
 		},
-		[ preventTooltipScroll, selectedIndex ]
+		[ focusWithoutScrollIfNeeded, selectedIndex ]
 	);
 
+	const previousTotalPoints = useRef( totalPoints );
+	const previousVisibleSeriesKey = useRef( visibleSeriesKey );
+
+	// Hiding or showing a series moves every index onto a different bar. The count alone misses a
+	// swap that keeps it the same, such as hiding one series while revealing another of equal length.
+	// Clear rather than clamp once focus has left the chart: a new tooltip would pull focus back.
+	useEffect( () => {
+		const countChanged = previousTotalPoints.current !== totalPoints;
+		const seriesChanged = previousVisibleSeriesKey.current !== visibleSeriesKey;
+		previousTotalPoints.current = totalPoints;
+		previousVisibleSeriesKey.current = visibleSeriesKey;
+
+		if ( ( ! countChanged && ! seriesChanged ) || selectedIndex === undefined ) {
+			return;
+		}
+
+		const { activeElement } = document;
+		const focusIsInChart = activeElement !== null && !! getChartRoot()?.contains( activeElement );
+
+		// A swap that leaves the count alone gives the same index a different series, so unlike a
+		// count change there is no shorter range to clamp into.
+		if ( totalPoints === 0 || ! focusIsInChart || ! countChanged ) {
+			setSelectedIndex( undefined );
+			setIsNavigating( false );
+			// Clearing unmounts the focused tooltip, which would drop focus to the body.
+			if ( focusIsInChart ) {
+				focusWithoutScrollIfNeeded( getChartRoot() );
+			}
+			return;
+		}
+
+		setSelectedIndex( Math.min( selectedIndex, totalPoints - 1 ) );
+	}, [
+		selectedIndex,
+		totalPoints,
+		visibleSeriesKey,
+		setSelectedIndex,
+		setIsNavigating,
+		getChartRoot,
+		focusWithoutScrollIfNeeded,
+	] );
+
 	// Returning focus from the tooltip must not restore the selection Escape just cleared.
 	const onChartFocus = useCallback(
 		( event: React.FocusEvent< HTMLDivElement > ) => {
@@ -247,46 +348,32 @@ export const useKeyboardNavigation = ( {
 
 	const onChartKeyDown = useCallback(
 		( event: React.KeyboardEvent< HTMLDivElement > ) => {
-			if ( totalPoints === 0 ) return;
-
-			const focusChart = () => {
-				if ( preventTooltipScroll ) {
-					chartRef.current?.focus( { preventScroll: true } );
-				} else {
-					chartRef.current?.focus();
+			if ( event.key === 'Tab' || event.key === 'Escape' ) {
+				// Consuming Escape with nothing open would swallow the first Escape of a surrounding Modal.
+				if ( event.key === 'Escape' && selectedIndex !== undefined ) {
+					event.preventDefault();
 				}
-			};
-
-			// Keep focus on the chart if tab is pressed
-			if ( event.key === 'Tab' ) {
-				focusChart();
+				focusWithoutScrollIfNeeded( getChartRoot() );
 				setSelectedIndex( undefined );
 				setIsNavigating( false );
 				return;
 			}
 
-			const currentSelectedIndex = selectedIndex === undefined ? -1 : selectedIndex;
-
-			if ( currentSelectedIndex + 1 >= totalPoints && [ 'ArrowRight' ].includes( event.key ) ) {
-				focusChart();
-				setSelectedIndex( undefined );
-				setIsNavigating( false );
-				return;
-			}
+			if ( totalPoints === 0 ) return;
 
-			event.preventDefault();
+			const currentSelectedIndex = selectedIndex === undefined ? -1 : selectedIndex;
 
-			if ( [ 'ArrowRight' ].includes( event.key ) ) {
+			// WAI-ARIA grid: arrows stop at the first and last cell.
+			if ( event.key === 'ArrowRight' ) {
+				event.preventDefault();
 				setIsNavigating( true );
-				setSelectedIndex( ( currentSelectedIndex + 1 ) % totalPoints );
-			} else if ( [ 'ArrowLeft' ].includes( event.key ) ) {
+				setSelectedIndex( Math.min( currentSelectedIndex + 1, totalPoints - 1 ) );
+			} else if ( event.key === 'ArrowLeft' ) {
+				event.preventDefault();
 				setIsNavigating( true );
-				setSelectedIndex( ( currentSelectedIndex - 1 + totalPoints ) % totalPoints );
-			} else if ( event.key === 'Escape' ) {
-				setSelectedIndex( undefined );
-				setIsNavigating( false );
-				focusChart();
+				setSelectedIndex( Math.max( currentSelectedIndex - 1, 0 ) );
 			} else if ( ( event.key === 'Enter' || event.key === ' ' ) && selectedIndex !== undefined ) {
+				event.preventDefault();
 				onActivate?.( selectedIndex );
 			}
 		},
@@ -295,9 +382,9 @@ export const useKeyboardNavigation = ( {
 			selectedIndex,
 			setSelectedIndex,
 			setIsNavigating,
-			chartRef,
+			getChartRoot,
+			focusWithoutScrollIfNeeded,
 			onActivate,
-			preventTooltipScroll,
 		]
 	);
 

package/src/components/tooltip/base-tooltip.module.scss

@@ -1,3 +1,5 @@
+// `.surface` is the look alone, for a chart that positions the box itself.
+.surface,
 .tooltip {
 	padding: var(--wpds-dimension-padding-sm);
 	// No WPDS token fits a translucent dark tooltip surface:
@@ -9,7 +11,10 @@
 	border-radius: var(--wpds-border-radius-md);
 	font-size: var(--wpds-typography-font-size-md);
 	box-shadow: var(--a8c-charts-elevation-sm, 0 1px 2px 0 #0000000d, 0 2px 3px 0 #0000000a, 0 6px 6px 0 #00000008, 0 8px 8px 0 #00000005);
-	position: absolute;
 	pointer-events: none;
+}
+
+.tooltip {
+	position: absolute;
 	transform: translate(-50%, -100%);
 }

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 = ( {