@automattic/charts 4.6.0 → 4.8.0

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

@@ -0,0 +1,189 @@
+import { MIN_LABEL_CONTRAST } from '../../../providers/chart-context/private/palette-generator';
+import {
+	blendRgb,
+	hexToRgb,
+	luminanceContrastRatio,
+	rgbLuminance,
+} from '../../../providers/chart-context/private/perceptual-color';
+import { getHeatmapScale } from '../../heatmap-chart/private/heatmap-scale';
+import {
+	pickLabelTextColor,
+	pickLabelTextColorForFill,
+	resolveLabelRoles,
+} from '../label-text-color';
+import type { Rgb } from '../../../providers/chart-context/private/perceptual-color';
+import type { LabelRoles, LabelTextColor, ResolvedRole } from '../label-text-color';
+
+const color = ( hex: string, alpha = 1 ): ResolvedRole => ( {
+	kind: 'color',
+	rgb: hexToRgb( hex ),
+	alpha,
+} );
+
+const unreadable = ( raw: string | null ): ResolvedRole => ( { kind: 'unreadable', raw } );
+
+const DEFAULT_ROLES: LabelRoles = { label: color( '#1e1e1e' ), labelInverse: color( '#f0f0f0' ) };
+
+const WHITE = hexToRgb( '#ffffff' );
+const MID_BLUE = hexToRgb( '#3858e9' );
+
+describe( 'resolveLabelRoles', () => {
+	const resolverFor =
+		( label: string | null, labelInverse: string | null ) =>
+		( value: string ): string | null =>
+			value.includes( '--a8c-charts-color-label-inverse' ) ? labelInverse : label;
+
+	it( 'resolves opaque roles in any syntax d3 reads', () => {
+		expect( resolveLabelRoles( resolverFor( '#1E1E1E', 'rgb(240, 240, 240)' ) ) ).toEqual(
+			DEFAULT_ROLES
+		);
+	} );
+
+	it( "keeps a role's alpha", () => {
+		expect( resolveLabelRoles( resolverFor( 'rgba(30, 30, 30, 0.87)', '#f0f0f0' ) ).label ).toEqual(
+			color( '#1e1e1e', 0.87 )
+		);
+	} );
+
+	it( 'reads transparent as a role with no alpha', () => {
+		expect( resolveLabelRoles( resolverFor( 'transparent', '#f0f0f0' ) ).label ).toEqual(
+			color( '#000000', 0 )
+		);
+	} );
+
+	it( 'keeps the raw value of a role it cannot read', () => {
+		expect( resolveLabelRoles( resolverFor( null, 'oklch(98% 0 0)' ) ) ).toEqual( {
+			label: unreadable( null ),
+			labelInverse: unreadable( 'oklch(98% 0 0)' ),
+		} );
+	} );
+} );
+
+describe( 'pickLabelTextColorForFill', () => {
+	it( 'keeps the default role before the roles are read', () => {
+		expect( pickLabelTextColorForFill( MID_BLUE, null, 'label' ) ).toBe( 'label' );
+		expect( pickLabelTextColorForFill( MID_BLUE, null, 'label-inverse' ) ).toBe( 'label-inverse' );
+	} );
+
+	it( 'picks the role that contrasts more when it reaches AA', () => {
+		expect( pickLabelTextColorForFill( WHITE, DEFAULT_ROLES, 'label-inverse' ) ).toBe( 'label' );
+		expect( pickLabelTextColorForFill( MID_BLUE, DEFAULT_ROLES, 'label' ) ).toBe( 'label-inverse' );
+	} );
+
+	it( 'falls back to black or white when neither role reaches AA', () => {
+		expect( pickLabelTextColorForFill( hexToRgb( '#516dec' ), DEFAULT_ROLES, 'label' ) ).toBe(
+			'black'
+		);
+		expect( pickLabelTextColorForFill( hexToRgb( '#4663ea' ), DEFAULT_ROLES, 'label' ) ).toBe(
+			'white'
+		);
+	} );
+
+	it( 'measures a translucent role as it paints over the fill', () => {
+		// Opaque, this label would read 16:1 on white; at 30% it paints a pale gray that fails AA.
+		const faintLabel: LabelRoles = {
+			label: color( '#1e1e1e', 0.3 ),
+			labelInverse: color( '#f0f0f0' ),
+		};
+
+		expect( pickLabelTextColorForFill( WHITE, faintLabel, 'label-inverse' ) ).toBe( 'black' );
+	} );
+
+	it( 'never picks a fully transparent role', () => {
+		const clearLabel: LabelRoles = {
+			label: color( '#000000', 0 ),
+			labelInverse: color( '#f0f0f0' ),
+		};
+
+		expect( pickLabelTextColorForFill( WHITE, clearLabel, 'label' ) ).toBe( 'black' );
+	} );
+
+	it( 'treats two different translucent roles as two colors', () => {
+		const translucent: LabelRoles = {
+			label: color( '#000000', 0.87 ),
+			labelInverse: color( '#ffffff', 0.9 ),
+		};
+
+		expect( pickLabelTextColorForFill( MID_BLUE, translucent, 'label' ) ).toBe( 'label-inverse' );
+	} );
+
+	it( 'uses a readable role when the other cannot be read, else black or white', () => {
+		const unreadableInverse: LabelRoles = {
+			label: color( '#1e1e1e' ),
+			labelInverse: unreadable( 'rgb(255 255 255)' ),
+		};
+
+		expect( pickLabelTextColorForFill( WHITE, unreadableInverse, 'label-inverse' ) ).toBe(
+			'label'
+		);
+		expect( pickLabelTextColorForFill( MID_BLUE, unreadableInverse, 'label' ) ).toBe( 'white' );
+	} );
+
+	it.each( [
+		[ 'readable', color( '#767676' ) ],
+		[ 'unreadable', unreadable( 'oklch(55% 0 0)' ) ],
+	] )( 'never falls back when both roles are the same %s color', ( _name, role ) => {
+		const pinned: LabelRoles = { label: role, labelInverse: { ...role } };
+
+		expect( pickLabelTextColorForFill( hexToRgb( '#516dec' ), pinned, 'label' ) ).toBe( 'label' );
+		expect( pickLabelTextColorForFill( hexToRgb( '#516dec' ), pinned, 'label-inverse' ) ).toBe(
+			'label-inverse'
+		);
+	} );
+
+	describe.each( [
+		[ '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' ) ),
+			black: 0,
+			white: 1,
+		};
+		// The Storybook custom accent, then the wp-admin scheme colors.
+		const primaries = [
+			'#4a19ab',
+			'#2271b1',
+			'#007cba',
+			'#3858e9',
+			'#437aa8',
+			'#916745',
+			'#646c3e',
+			'#cf4339',
+			'#567958',
+			'#ad631e',
+		];
+
+		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( 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 );
+				const painted8Bit: Rgb = [ r, g, b ];
+
+				for ( const shown of [ fill, painted8Bit ] ) {
+					expect(
+						luminanceContrastRatio( rgbLuminance( shown ), painted[ choice ] )
+					).toBeGreaterThanOrEqual( MIN_LABEL_CONTRAST );
+				}
+			}
+		} );
+	} );
+} );
+
+describe( 'pickLabelTextColor', () => {
+	it( 'reads the fill from any color syntax', () => {
+		expect( pickLabelTextColor( 'rgb(255, 255, 255)', DEFAULT_ROLES, 'label-inverse' ) ).toBe(
+			'label'
+		);
+	} );
+
+	it( 'keeps the default role for a fill it cannot read', () => {
+		expect( pickLabelTextColor( 'var(--not-set)', DEFAULT_ROLES, 'label-inverse' ) ).toBe(
+			'label-inverse'
+		);
+	} );
+} );

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

@@ -3,6 +3,7 @@ import { useContext } from 'react';
 import { ChartScopeContext } from '../../../../providers/chart-scope';
 import { withResponsive } from '../index';
 import type { BaseChartProps } from '../../../../types';
+import type { JSX } from 'react';
 
 // Mock the useParentSize hook
 jest.mock( '@visx/responsive', () => ( {

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

@@ -1,6 +1,7 @@
 import { useParentSize } from '@visx/responsive';
 import clsx from 'clsx';
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { useIsomorphicLayoutEffect } from '../../../hooks';
 import { ChartScopeContext } from '../../../providers/chart-scope';
 import styles from './with-responsive.module.scss';
 import type { BaseChartProps } from '../../../types';
@@ -33,10 +34,6 @@ export type ResponsiveConfig = {
 	resizeDebounceTime?: number;
 };
 
-// useLayoutEffect on the client (so containment is resolved before paint, no flash),
-// useEffect on the server to avoid React's SSR warning.
-const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
-
 /**
  * A higher-order component that provides responsive dimensions
  * to the wrapped chart component using useParentSize from `@visx/responsive`.

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

@@ -1,35 +1,32 @@
-import { formatNumber } from '@automattic/number-formatters';
-import clsx from 'clsx';
-import { useStandaloneScopeClass } from '../../providers/chart-scope';
-import styles from './base-tooltip.module.scss';
+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;
 };
@@ -42,38 +39,42 @@ 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,
 	renderContainer = true,
 }: BaseTooltipProps ) => {
 	const content = children || ( data && <Component data={ data } className={ className } /> );
-	const standaloneScopeClass = useStandaloneScopeClass();
 
 	if ( ! renderContainer ) {
 		return content;
 	}
 
-	return (
-		<div
-			className={ clsx( standaloneScopeClass, styles.tooltip ) }
-			style={ { top, left, ...style } }
-			role="tooltip"
-		>
-			{ content }
-		</div>
-	);
+	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,15 +1,19 @@
-import { Tooltip, defaultStyles } from '@visx/tooltip';
 import { useLayoutEffect, useRef, useState } from 'react';
+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;
 };
 
@@ -27,6 +31,15 @@ const isClipping = ( element: Element ) => {
 	return [ overflow, overflowX, overflowY ].some( value => value && value !== 'visible' );
 };
 
+// The positioned wrapper the box renders into, past the tooltip theme's `display: contents` element, which has no box to measure.
+const findLayoutParent = ( node: Element ): Element | null => {
+	let element = node.parentElement;
+	while ( element && getComputedStyle( element ).display === 'contents' ) {
+		element = element.parentElement;
+	}
+	return element;
+};
+
 // The first ancestor that cuts its overflow off. The box may leave the chart
 // wrapper but never this element, which is what a body-level portal used to
 // guarantee by never being inside one.
@@ -122,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
@@ -131,13 +144,14 @@ 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.
  * @param props.offsetTop  - Gap between the anchor and the box, vertically.
- * @param props.style      - Box styles; visx's defaults unless `unstyled`.
- * @param props.unstyled   - Skip `style` and leave the box bare.
+ * @param props.style      - Inline overrides on the surface; ignored when `unstyled`.
+ * @param props.unstyled   - Drop the surface and `style`, leaving the box bare.
+ * @param props.className  - Extra classes beside the surface.
  * @param props.children   - Box content.
  * @param props.placement  - Below-axis, beside without vertical flipping, or automatic flipping.
  * @return The tooltip box.
@@ -147,8 +161,9 @@ export const BoundedTooltip = ( {
 	top = 0,
 	offsetLeft = DEFAULT_OFFSET,
 	offsetTop = DEFAULT_OFFSET,
-	style = defaultStyles,
+	style,
 	unstyled = false,
+	className,
 	children,
 	placement = 'auto',
 	...rest
@@ -159,7 +174,7 @@ export const BoundedTooltip = ( {
 
 	useLayoutEffect( () => {
 		const node = nodeRef.current;
-		const wrapper = node?.parentElement;
+		const wrapper = node && findLayoutParent( node );
 		if ( ! node || ! wrapper ) {
 			return;
 		}
@@ -199,9 +214,12 @@ export const BoundedTooltip = ( {
 	const y = position?.y ?? top + ( placement === 'below-axis' ? POINTER_HEIGHT : offsetTop );
 
 	return (
-		<Tooltip
+		<TooltipBox
 			ref={ nodeRef }
+			role="presentation"
 			data-testid="bounded-tooltip"
+			unstyled={ unstyled }
+			className={ className }
 			style={ {
 				position: 'absolute',
 				left: 0,
@@ -220,14 +238,15 @@ export const BoundedTooltip = ( {
 						left: left - x - POINTER_HEIGHT,
 						top: -POINTER_HEIGHT,
 						width: POINTER_HEIGHT * 2,
-						height: POINTER_HEIGHT,
+						// One extra pixel overlaps the box, so anti-aliasing leaves no seam between them.
+						height: POINTER_HEIGHT + 1,
 						background: 'inherit',
-						clipPath: 'polygon(50% 0, 100% 100%, 0 100%)',
+						clipPath: `polygon(50% 0, 100% ${ POINTER_HEIGHT }px, 100% 100%, 0 100%, 0 ${ POINTER_HEIGHT }px)`,
 						pointerEvents: 'none',
 					} }
 				/>
 			) }
 			{ children }
-		</Tooltip>
+		</TooltipBox>
 	);
 };

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 ) }
+	</>
+);

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

@@ -0,0 +1,37 @@
+import { color as d3Color } from '@visx/vendor/d3-color';
+import { ThemeProvider } from '@wordpress/theme';
+import { useMemo } from 'react';
+import { useChartScopeElement } from '../../../providers/chart-scope';
+import { resolveCssVariable } from '../../../utils/resolve-css-var';
+import type { ReactNode } from 'react';
+
+const DEFAULT_SURFACE = '#1e1e1e';
+const TOOLTIP_SURFACE = `var(--a8c-charts-color-tooltip-surface, ${ DEFAULT_SURFACE })`;
+
+// `ThemeProvider` throws on a seed that is not an opaque sRGB color, which would unmount the chart.
+const toSeed = ( value: string | null ) => {
+	const parsed = value ? d3Color( value ) : null;
+	return parsed && parsed.opacity === 1 ? parsed.formatHex() : DEFAULT_SURFACE;
+};
+
+/**
+ * Themes the tooltip box for its dark surface, as `@wordpress/ui`'s Tooltip themes its popup. The box re-declares the catalog under this theme, so every role it reads is tuned for the surface, whatever theme the chart is in.
+ *
+ * @param props          - Component props.
+ * @param props.children - The tooltip box.
+ * @return The themed box.
+ */
+export const TooltipTheme = ( { children }: { children: ReactNode } ) => {
+	const scopeElement = useChartScopeElement();
+	const color = useMemo(
+		() => ( { background: toSeed( resolveCssVariable( TOOLTIP_SURFACE, scopeElement ) ) } ),
+		[ scopeElement ]
+	);
+
+	// Core's `wp-theme` in WordPress 7.0 exports only `privateApis`.
+	if ( ! ThemeProvider ) {
+		return <>{ children }</>;
+	}
+
+	return <ThemeProvider color={ color }>{ children }</ThemeProvider>;
+};