@automattic/charts 4.7.0 → 4.9.0

package/src/charts/private/pie-keyboard-navigation/selected-segment-ring.tsx

@@ -0,0 +1,47 @@
+import styles from './pie-keyboard-navigation.module.scss';
+
+interface SelectedSegmentRingProps {
+	/** The chart's id, which keeps the clip path unique on a page with several charts. */
+	chartId: string;
+	/** The selected segment's path, from the same arc generator that draws the segment. */
+	d: string;
+}
+
+/**
+ * Encodes `value` for an SVG id, losslessly so distinct chart ids never share a clip path.
+ *
+ * @param value - Any string.
+ * @return `value` with each character outside `[A-Za-z0-9-]` written as `_<hex code point>_`.
+ */
+export const toSvgId = ( value: string ) =>
+	Array.from( value, character =>
+		/[A-Za-z0-9-]/.test( character )
+			? character
+			: `_${ character.codePointAt( 0 )?.toString( 16 ) }_`
+	).join( '' );
+
+/**
+ * Marks the selected segment with a two-tone ring drawn inside its edge, so the SVG edge cannot cut it off.
+ *
+ * @param {SelectedSegmentRingProps} props - Component props
+ * @return {JSX.Element} The ring
+ */
+export const SelectedSegmentRing = ( { chartId, d }: SelectedSegmentRingProps ) => {
+	const clipId = `pie-selected-ring-clip-${ toSvgId( chartId ) }`;
+	const clipPath = `url(#${ clipId })`;
+
+	return (
+		<g pointerEvents="none" aria-hidden="true">
+			<clipPath id={ clipId }>
+				<path d={ d } />
+			</clipPath>
+			<path d={ d } clipPath={ clipPath } className={ styles[ 'selected-ring__contrast' ] } />
+			<path
+				d={ d }
+				clipPath={ clipPath }
+				className={ styles[ 'selected-ring__focus' ] }
+				data-testid="pie-selected-ring"
+			/>
+		</g>
+	);
+};

package/src/charts/private/pie-keyboard-navigation/test/order-arcs-for-navigation.test.ts

@@ -0,0 +1,34 @@
+import { orderArcsForNavigation } from '../order-arcs-for-navigation';
+
+const half = Math.PI / 2;
+
+describe( 'orderArcsForNavigation', () => {
+	it.each( [
+		[
+			'full pie, clockwise from 12 o’clock',
+			[
+				{ id: 'b', startAngle: Math.PI, endAngle: 2 * Math.PI },
+				{ id: 'a', startAngle: 0, endAngle: Math.PI },
+			],
+			[ 'a', 'b' ],
+		],
+		[
+			'clockwise semi-circle, left to right',
+			[
+				{ id: 'right', startAngle: 0, endAngle: half },
+				{ id: 'left', startAngle: -half, endAngle: 0 },
+			],
+			[ 'left', 'right' ],
+		],
+		[
+			'counter-clockwise semi-circle, left to right',
+			[
+				{ id: 'right', startAngle: half, endAngle: 0 },
+				{ id: 'left', startAngle: 0, endAngle: -half },
+			],
+			[ 'left', 'right' ],
+		],
+	] )( 'orders a %s', ( _, arcs, expected ) => {
+		expect( orderArcsForNavigation( arcs ).map( arc => arc.id ) ).toEqual( expected );
+	} );
+} );

package/src/charts/private/pie-keyboard-navigation/test/selected-segment-ring.test.ts

@@ -0,0 +1,14 @@
+import { toSvgId } from '../selected-segment-ring';
+
+describe( 'toSvgId', () => {
+	it.each( [
+		[ 'devices:1', 'devices/1' ],
+		[ 'a_3a_', 'a:' ],
+		[ ':r1:', '_r1_' ],
+	] )( 'keeps %s and %s apart', ( first, second ) => {
+		const ids = [ toSvgId( first ), toSvgId( second ) ];
+
+		expect( ids[ 0 ] ).not.toBe( ids[ 1 ] );
+		ids.forEach( id => expect( id ).toMatch( /^[A-Za-z0-9_-]+$/ ) );
+	} );
+} );

package/src/charts/private/pie-keyboard-navigation/use-pie-keyboard-navigation.ts

@@ -0,0 +1,139 @@
+import { useTooltip } from '@visx/tooltip';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useKeyboardNavigation } from '../../../components/tooltip';
+import type { DataPointPercentageCalculated } from '../../../types';
+import type { MouseEvent } from 'react';
+
+interface UsePieKeyboardNavigationProps< Arc > {
+	/** The visible arcs in `orderArcsForNavigation` order, which indexes run over. */
+	navigationArcs: Arc[];
+	withTooltips: boolean;
+	tooltipOffsetX: number;
+	tooltipOffsetY: number;
+}
+
+export const usePieKeyboardNavigation = < Arc extends { data: DataPointPercentageCalculated } >( {
+	navigationArcs,
+	withTooltips,
+	tooltipOffsetX,
+	tooltipOffsetY,
+}: UsePieKeyboardNavigationProps< Arc > ) => {
+	const chartRef = useRef< HTMLDivElement >( null );
+	const svgRef = useRef< SVGSVGElement >( null );
+	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
+	const [ isNavigating, setIsNavigating ] = useState( false );
+	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
+		useTooltip< DataPointPercentageCalculated >();
+
+	const {
+		tooltipRef: focusTooltip,
+		onChartFocus,
+		onChartBlur,
+		onChartKeyDown,
+		onChartPointerMove,
+	} = useKeyboardNavigation( {
+		selectedIndex,
+		setSelectedIndex,
+		isNavigating,
+		setIsNavigating,
+		chartRef,
+		totalPoints: navigationArcs.length,
+		visibleSeriesKey: JSON.stringify( navigationArcs.map( arcDatum => arcDatum.data.label ) ),
+	} );
+
+	const selectedArc = selectedIndex === undefined ? undefined : navigationArcs[ selectedIndex ];
+
+	const keyboardTooltip = useRef< HTMLDivElement | null >( null );
+	const tooltipLostFocus = useRef( false );
+
+	// React detaches the ref before removing the node, so the tooltip still holds focus here.
+	const tooltipRef = useCallback(
+		( element: HTMLDivElement | null ) => {
+			if ( element ) {
+				keyboardTooltip.current = element;
+				focusTooltip( element );
+			} else if (
+				keyboardTooltip.current?.ownerDocument.activeElement === keyboardTooltip.current
+			) {
+				tooltipLostFocus.current = true;
+			}
+		},
+		[ focusTooltip ]
+	);
+
+	// Arrow keys mount the next tooltip in the same commit, so focus only reaches the body when the selection's tooltip went away.
+	useLayoutEffect( () => {
+		if ( ! tooltipLostFocus.current ) {
+			return;
+		}
+		tooltipLostFocus.current = false;
+		const { activeElement, body } = chartRef.current?.ownerDocument ?? document;
+		if ( activeElement === null || activeElement === body ) {
+			chartRef.current?.focus();
+		}
+	} );
+
+	const getSegmentHandlers = ( data: DataPointPercentageCalculated, navigationIndex: number ) => ( {
+		onMouseMove: ( event: MouseEvent< SVGElement > ) => {
+			onChartPointerMove( navigationIndex );
+			if ( ! withTooltips ) {
+				return;
+			}
+
+			// The tooltip renders inside `chartRef`, so pointer coordinates are taken relative to it.
+			const bounds = chartRef.current?.getBoundingClientRect();
+			if ( ! bounds ) {
+				return;
+			}
+
+			showTooltip( {
+				tooltipData: data,
+				tooltipLeft: event.clientX - bounds.left + tooltipOffsetX,
+				tooltipTop: event.clientY - bounds.top + tooltipOffsetY,
+			} );
+		},
+		onMouseLeave: withTooltips ? hideTooltip : undefined,
+	} );
+
+	/**
+	 * Anchors the keyboard tooltip at `point`, an offset from the origin of the group the arcs are drawn in.
+	 *
+	 * @param originX - The group's x in SVG coordinates.
+	 * @param originY - The group's y in SVG coordinates.
+	 * @param point   - The point relative to the group, such as an arc centroid.
+	 * @return The anchor in SVG coordinates, or undefined without tooltips.
+	 */
+	const getKeyboardTooltipAnchor = useCallback(
+		( originX: number, originY: number, [ x, y ]: [ number, number ] ) =>
+			withTooltips
+				? { left: originX + x + tooltipOffsetX, top: originY + y + tooltipOffsetY }
+				: undefined,
+		[ withTooltips, tooltipOffsetX, tooltipOffsetY ]
+	);
+
+	return {
+		chartRef,
+		svgRef,
+		selectedArc,
+		getSegmentHandlers,
+		getKeyboardTooltipAnchor,
+		selectionOutputProps: {
+			withTooltips,
+			selectedIndex,
+			selectedData: selectedArc?.data,
+			chartRef,
+			svgRef,
+			tooltipRef,
+			pointerTooltip: tooltipOpen
+				? { data: tooltipData, left: tooltipLeft || 0, top: tooltipTop || 0 }
+				: undefined,
+		},
+		chartProps: {
+			role: 'application',
+			tabIndex: 0,
+			onKeyDown: onChartKeyDown,
+			onFocus: onChartFocus,
+			onBlur: onChartBlur,
+		} as const,
+	};
+};

package/src/charts/private/test/label-text-color.test.ts

@@ -5,6 +5,7 @@ import {
 	luminanceContrastRatio,
 	rgbLuminance,
 } from '../../../providers/chart-context/private/perceptual-color';
+import { getHeatmapScale } from '../../heatmap-chart/private/heatmap-scale';
 import {
 	pickLabelTextColor,
 	pickLabelTextColorForFill,
@@ -131,9 +132,9 @@ describe( 'pickLabelTextColorForFill', () => {
 	} );
 
 	describe.each( [
-		[ 'white', '#ffffff' ],
-		[ 'dark', '#1e1e1e' ],
-	] )( 'across a heatmap scale on a %s background', ( _name, background ) => {
+		[ 'white', '#ffffff', '#f0f0f0' ],
+		[ 'dark', '#242424', '#272727' ],
+	] )( 'across a heatmap scale on a %s background', ( _name, background, emptyCell ) => {
 		const painted: Record< LabelTextColor, number > = {
 			label: rgbLuminance( hexToRgb( '#1e1e1e' ) ),
 			'label-inverse': rgbLuminance( hexToRgb( '#f0f0f0' ) ),
@@ -155,12 +156,9 @@ describe( 'pickLabelTextColorForFill', () => {
 		];
 
 		it.each( primaries )( 'reaches AA on every intensity of %s', primary => {
+			const { low, high } = getHeatmapScale( primary, background, emptyCell );
 			for ( let step = 0; step <= 200; step++ ) {
-				const fill = blendRgb(
-					hexToRgb( primary ),
-					hexToRgb( background ),
-					0.15 + 0.85 * ( step / 200 )
-				);
+				const fill = blendRgb( hexToRgb( high ), hexToRgb( low ), step / 200 );
 				const choice = pickLabelTextColorForFill( fill, DEFAULT_ROLES, 'label' );
 				// Checked on the 8-bit channels the browser paints as well as the exact mix.
 				const [ r, g, b ] = fill.map( Math.round );

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

@@ -212,11 +212,12 @@ describe( 'ZoomResetButton', () => {
 
 	test( 'keyboard activation survives the chart wrapper keydown handler', async () => {
 		const onClick = jest.fn();
-		// Mirrors the chart's grid wrapper, whose keyboard-navigation handler
+		// Mirrors the chart's focusable container, whose keyboard-navigation handler
 		// calls preventDefault() on bubbled keydowns — which would cancel the
 		// native Enter/Space button activation.
 		render(
-			<div role="grid" tabIndex={ 0 } onKeyDown={ preventDefaultKeydown }>
+			// eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- mirrors the charts' container.
+			<div role="application" tabIndex={ 0 } onKeyDown={ preventDefaultKeydown }>
 				<ZoomResetButton onClick={ onClick } />
 			</div>
 		);

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

@@ -1,36 +1,32 @@
-import { formatNumber } from '@automattic/number-formatters';
-import clsx from 'clsx';
-import { CHART_SCOPE_CLASS } from '../../styles/chart-scope-class';
-import styles from './base-tooltip.module.scss';
-import { TooltipTheme } from './private/tooltip-theme';
+import { LabelValueContent } from './private/label-value-content';
+import { TooltipBox } from './tooltip-box';
+import type { TooltipData } from './types';
 import type { CSSProperties, ComponentType, ReactNode } from 'react';
 
-type TooltipData = {
-	label: string;
-	value: number;
-	valueDisplay?: string;
-};
-
 type TooltipComponentProps = {
 	data: TooltipData;
 	className?: string;
 };
 
 type TooltipCommonProps = {
-	top: number;
-	left: number;
+	/** @deprecated Position the box with `style`, or use `TooltipBox`. */
+	top?: number;
+	/** @deprecated Position the box with `style`, or use `TooltipBox`. */
+	left?: number;
 	style?: CSSProperties;
 	className?: string;
 	/**
 	 * Whether to render the tooltip container div. When false, only renders the content.
-	 * Useful when the tooltip is rendered inside a portal or custom container.
+	 * @deprecated Render the content directly; `TooltipBox` draws the box.
 	 * @default true
 	 */
 	renderContainer?: boolean;
 };
 
 type DefaultDataTooltip = {
+	/** @deprecated Pass the content as children, or use `TooltipBox`. */
 	data: TooltipData;
+	/** @deprecated Pass the content as children, or use `TooltipBox`. */
 	component?: ComponentType< TooltipComponentProps >;
 	children?: never;
 };
@@ -43,17 +39,25 @@ type CustomTooltip = {
 
 type BaseTooltipProps = TooltipCommonProps & ( DefaultDataTooltip | CustomTooltip );
 
-const DefaultTooltipContent = ( { data }: TooltipComponentProps ) => (
-	<>
-		{ data?.label }: { data?.valueDisplay || formatNumber( data?.value ) }
-	</>
-);
-
+/**
+ * A tooltip box with children or `label: value` content. Prefer `TooltipBox`.
+ *
+ * @param props                 - Tooltip props.
+ * @param props.data            - Data for the default content.
+ * @param props.top             - Deprecated vertical position.
+ * @param props.left            - Deprecated horizontal position.
+ * @param props.component       - Deprecated content component.
+ * @param props.children        - Tooltip content.
+ * @param props.className       - Class name passed to the content component.
+ * @param props.style           - Styles for the box.
+ * @param props.renderContainer - Deprecated; render the content alone when false.
+ * @return The tooltip.
+ */
 export const BaseTooltip = ( {
 	data,
 	top,
 	left,
-	component: Component = DefaultTooltipContent,
+	component: Component = LabelValueContent,
 	children,
 	className,
 	style,
@@ -65,17 +69,12 @@ export const BaseTooltip = ( {
 		return content;
 	}
 
-	return (
-		<TooltipTheme>
-			<div
-				className={ clsx( CHART_SCOPE_CLASS, styles.tooltip ) }
-				style={ { top, left, ...style } }
-				role="tooltip"
-			>
-				{ content }
-			</div>
-		</TooltipTheme>
-	);
+	const placement =
+		top === undefined && left === undefined
+			? undefined
+			: ( { position: 'absolute', top, left, transform: 'translate(-50%, -100%)' } as const );
+
+	return <TooltipBox style={ { ...placement, ...style } }>{ content }</TooltipBox>;
 };
 
 export type { BaseTooltipProps, TooltipData };

package/src/components/tooltip/index.ts

@@ -1,4 +1,6 @@
 export { BaseTooltip } from './base-tooltip';
-export { AccessibleTooltip, useKeyboardNavigation } from './accessible-tooltip';
+export { AccessibleTooltip, XYChartTooltip, useKeyboardNavigation } from './xy-chart-tooltip';
+export { TooltipBox } from './tooltip-box';
 export type { BaseTooltipProps, TooltipData } from './base-tooltip';
+export type { TooltipBoxProps } from './tooltip-box';
 export type { TooltipProps } from './types';

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

@@ -1,19 +1,19 @@
-import { Tooltip } from '@visx/tooltip';
-import clsx from 'clsx';
 import { useLayoutEffect, useRef, useState } from 'react';
-import { TOOLTIP_SCOPE_CLASS } from '../../../styles/chart-scope-class';
-import styles from '../base-tooltip.module.scss';
-import { TooltipTheme } from './tooltip-theme';
+import { TooltipBox } from '../tooltip-box';
 import type { TooltipPlacement } from '../../../visx/types';
-import type { TooltipProps } from '@visx/tooltip';
+import type { TooltipBoxProps } from '../tooltip-box';
+import type { ReactNode } from 'react';
 
 type Bounds = { left: number; top: number; right: number; bottom: number };
 type Size = { width: number; height: number };
 
-export type BoundedTooltipProps = Omit< TooltipProps, 'left' | 'top' | 'applyPositionStyle' > & {
+export type BoundedTooltipProps = Omit< TooltipBoxProps, 'children' > & {
+	children?: ReactNode;
 	/** Anchor, in the coordinates of the positioned wrapper the box renders into. */
 	left?: number;
 	top?: number;
+	offsetLeft?: number;
+	offsetTop?: number;
 	placement?: TooltipPlacement;
 };
 
@@ -135,7 +135,7 @@ export const getBoundedPosition = ( {
 };
 
 /**
- * visx's `Tooltip`, positioned like its `TooltipWithBounds` but kept inside the
+ * A `TooltipBox`, positioned like visx's `TooltipWithBounds` but kept inside the
  * nearest clipping ancestor — or the viewport when there is none — rather than
  * inside its own parent. Rendered in-tree, a tooltip's parent is the chart
  * wrapper, which is often narrower than the box; measuring against the parent
@@ -144,7 +144,7 @@ export const getBoundedPosition = ( {
  * Re-measures on every render, so a box whose content changes width between
  * two hovers is placed for its current size.
  *
- * @param props            - visx `Tooltip` props.
+ * @param props            - `TooltipBox` props plus placement.
  * @param props.left       - Anchor x, in wrapper coordinates.
  * @param props.top        - Anchor y, in wrapper coordinates.
  * @param props.offsetLeft - Gap between the anchor and the box, horizontally.
@@ -213,11 +213,13 @@ export const BoundedTooltip = ( {
 	const x = position?.x ?? left + offsetLeft;
 	const y = position?.y ?? top + ( placement === 'below-axis' ? POINTER_HEIGHT : offsetTop );
 
-	const box = (
-		<Tooltip
+	return (
+		<TooltipBox
 			ref={ nodeRef }
+			role="presentation"
 			data-testid="bounded-tooltip"
-			className={ clsx( ! unstyled && [ TOOLTIP_SCOPE_CLASS, styles.surface ], className ) }
+			unstyled={ unstyled }
+			className={ className }
 			style={ {
 				position: 'absolute',
 				left: 0,
@@ -245,8 +247,6 @@ export const BoundedTooltip = ( {
 				/>
 			) }
 			{ children }
-		</Tooltip>
+		</TooltipBox>
 	);
-
-	return unstyled ? box : <TooltipTheme>{ box }</TooltipTheme>;
 };

package/src/components/tooltip/private/label-value-content.tsx

@@ -0,0 +1,8 @@
+import { formatNumber } from '@automattic/number-formatters';
+import type { TooltipData } from '../types';
+
+export const LabelValueContent = ( { data }: { data: TooltipData } ) => (
+	<>
+		{ data.label }: { data.valueDisplay || formatNumber( data.value ) }
+	</>
+);