Premium Analytics: Show highlight metric notes in a tooltip (#54011)

* Premium Analytics: Add a tooltip for metric notes

The highlight grids show each metric's note in a native title, which
appears late, uses browser styling, and never shows for keyboard users.
This component makes the noted element a WPDS Tooltip trigger and a tab
stop, so the note opens on hover and on focus. Assistive tech reads the
visually hidden copy in the trigger, and the popup is hidden from it, so
the note is read once.

* Premium Analytics: Show tile notes in a tooltip

Site overview, Post detail and Subscriber highlights put each tile's
note in a native title, which keyboard users never see. The tile header
now opens the note in the WPDS tooltip on hover and on focus.

* Premium Analytics: Show post highlight notes in a tooltip

The post highlight card put each metric's note in a native title on
the whole metric, which keyboard users never see. The note now opens in
the WPDS tooltip from the metric label. The trigger stops at the label
because a shortened value already opens its own tooltip with the exact
figure, and one hover must not open both.

* Premium Analytics: Add changelog entries for metric note tooltips

The plugins that show the highlight grids follow the same set as the
change that added the notes: the Premium Analytics plugin, Jetpack, and
wpcomsh, which gets the dashboard through jetpack-mu-wpcom.

* Address review: Stop asserting the removed note title (Codex P1 #1)

Site overview and Subscriber highlights tests still looked each note up
by its native title, which the tooltip replaced, so they failed. The
visually hidden copy already shows which note each tile carries, and the
tooltip itself is tested once in MetricNoteTooltip.

* Address review: Keep the hidden note popup out of focus (Codex P2 #1)

Base UI renders the tooltip popup with tabindex -1, so the aria-hidden
popup could still take focus programmatically. A focused element hidden
from assistive tech strands a screen reader user on nothing. The note is
not interactive, so the popup now drops the tabindex.

* Address review: Name the plain div in the note docblock

The final review found "a plain box" vague for the element a metric with no note renders.

* Address review: Drop the wpcomsh changelog entry

wpcomsh stopped bundling Premium Analytics in #52717, so its users never see this change. The Jetpack entry already covers Atomic sites.

Author: adamwoodnz

projects/packages/premium-analytics/changelog/wooa7s-2203-highlight-grids-show-metric-notes-in-a-tooltip-not-the

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Highlights: Show metric notes in a styled tooltip that also opens on keyboard focus.

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-note-tooltip/__tests__/metric-note-tooltip.test.tsx

@@ -0,0 +1,59 @@
+/**
+ * External dependencies
+ */
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+/**
+ * Internal dependencies
+ */
+import { MetricNoteTooltip } from '../metric-note-tooltip';
+
+const NOTE = 'Sum of daily visitors.';
+
+type User = ReturnType< typeof userEvent.setup >;
+
+function setup( note?: string ) {
+	const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
+	render( <MetricNoteTooltip note={ note }>Visitors</MetricNoteTooltip> );
+	return user;
+}
+
+async function settle() {
+	await act( () => jest.runAllTimersAsync() );
+}
+
+describe( 'MetricNoteTooltip', () => {
+	beforeEach( () => jest.useFakeTimers() );
+	afterEach( () => jest.useRealTimers() );
+
+	it.each( [
+		[ 'hover', ( user: User ) => user.hover( screen.getByText( 'Visitors' ) ) ],
+		[ 'keyboard focus', ( user: User ) => user.tab() ],
+	] )( 'shows the note in a tooltip on %s', async ( _, open ) => {
+		const user = setup( NOTE );
+
+		await open( user );
+		await settle();
+
+		expect( screen.getByTestId( 'metric-note-tooltip' ) ).toHaveTextContent( NOTE );
+	} );
+
+	it( 'gives assistive tech the note once, while the tooltip is open', async () => {
+		const user = setup( NOTE );
+
+		await user.tab();
+		await settle();
+
+		expect( screen.getAllByText( NOTE ) ).toHaveLength( 2 );
+		expect( screen.getByTestId( 'metric-note-tooltip' ) ).toHaveAttribute( 'aria-hidden', 'true' );
+		expect( screen.getByTestId( 'metric-note-tooltip' ) ).not.toHaveAttribute( 'tabindex' );
+	} );
+
+	it( 'leaves a metric with no note out of the tab order', async () => {
+		const user = setup();
+
+		await user.tab();
+
+		expect( document.body ).toHaveFocus();
+	} );
+} );

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-note-tooltip/index.ts

@@ -0,0 +1,2 @@
+export { MetricNoteTooltip } from './metric-note-tooltip';
+export type { MetricNoteTooltipProps } from './metric-note-tooltip';

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-note-tooltip/metric-note-tooltip.module.scss

@@ -0,0 +1,8 @@
+// Widget roots clip overflow, so the focus ring is drawn inset.
+.trigger:focus-visible {
+	border-radius: var(--wpds-border-radius-sm);
+	outline:
+		var(--wpds-border-width-focus) solid
+		var(--wpds-color-stroke-focus);
+	outline-offset: calc(-1 * var(--wpds-border-width-focus));
+}

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-note-tooltip/metric-note-tooltip.tsx

@@ -0,0 +1,49 @@
+/**
+ * External dependencies
+ */
+import { Tooltip, VisuallyHidden } from '@jetpack-premium-analytics/externals';
+import clsx from 'clsx';
+/**
+ * Internal dependencies
+ */
+import styles from './metric-note-tooltip.module.scss';
+import type { ReactNode } from 'react';
+
+export type MetricNoteTooltipProps = {
+	/**
+	 * Caveat about how the metric is aggregated. Without one, the children render in a plain `div`.
+	 */
+	note?: string;
+
+	className?: string;
+
+	children: ReactNode;
+};
+
+/**
+ * Shows a metric's note in a tooltip on hover and keyboard focus, and reads it once to assistive tech.
+ *
+ * @param {MetricNoteTooltipProps} props - The component props.
+ * @return The rendered box.
+ */
+export function MetricNoteTooltip( { note, className, children }: MetricNoteTooltipProps ) {
+	if ( ! note ) {
+		return <div className={ className }>{ children }</div>;
+	}
+
+	return (
+		<Tooltip.Root>
+			<Tooltip.Trigger
+				render={ <div className={ clsx( styles.trigger, className ) } tabIndex={ 0 } /> }
+			>
+				{ children }
+				<VisuallyHidden>{ note }</VisuallyHidden>
+			</Tooltip.Trigger>
+			{ /* Assistive tech reads the copy in the trigger, so the popup is hidden, and
+			     drops the `tabIndex={-1}` Base UI gives it so nothing hidden can take focus. */ }
+			<Tooltip.Popup aria-hidden="true" tabIndex={ undefined } data-testid="metric-note-tooltip">
+				{ note }
+			</Tooltip.Popup>
+		</Tooltip.Root>
+	);
+}

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-tile/__tests__/metric-tile-grid.test.tsx

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { comment, postList } from '@wordpress/icons';
 /**
  * Internal dependencies
@@ -22,6 +23,8 @@ function renderMetricGrid() {
 }
 
 describe( 'MetricTileGrid', () => {
+	afterEach( () => jest.useRealTimers() );
+
 	it( 'renders metric tiles as a list', () => {
 		renderMetricGrid();
 
@@ -73,7 +76,9 @@ describe( 'MetricTileGrid', () => {
 		expect( screen.queryByText( /%/ ) ).not.toBeInTheDocument();
 	} );
 
-	it( 'exposes a tile note as visually hidden assistive text', () => {
+	it( 'shows a tile note in a tooltip on the tile header', async () => {
+		jest.useFakeTimers();
+		const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
 		render(
 			<MetricTileGrid
 				tiles={ [
@@ -82,6 +87,11 @@ describe( 'MetricTileGrid', () => {
 			/>
 		);
 
-		expect( screen.getByText( 'Sum of daily visitors.' ) ).toBeInTheDocument();
+		await user.hover( screen.getByText( 'Visitors' ) );
+		await act( () => jest.runAllTimersAsync() );
+
+		expect( screen.getByTestId( 'metric-note-tooltip' ) ).toHaveTextContent(
+			'Sum of daily visitors.'
+		);
 	} );
 } );

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/metric-tile/metric-tile-grid.tsx

@@ -1,11 +1,12 @@
 /**
  * External dependencies
  */
-import { Icon, Text, VisuallyHidden } from '@jetpack-premium-analytics/externals';
+import { Icon, Text } from '@jetpack-premium-analytics/externals';
 import clsx from 'clsx';
 /**
  * Internal dependencies
  */
+import { MetricNoteTooltip } from '../metric-note-tooltip';
 import { MetricValue } from '../metric-value';
 import { MetricWithComparison } from '../metric-with-comparison';
 import styles from './metric-tile-grid.module.scss';
@@ -43,8 +44,7 @@ type MetricTileGridItem = {
 	previousValue?: number | null;
 
 	/**
-	 * Caveat about how the value is aggregated. Shown as a hover tooltip on the
-	 * tile header and mirrored as visually hidden text for assistive technology.
+	 * Caveat about how the value is aggregated, shown in a tooltip on the tile header.
 	 */
 	note?: string;
 
@@ -158,13 +158,10 @@ export function MetricTileGrid( {
 			<div className={ styles.grid } data-layout={ layout } role="list">
 				{ tiles.map( tile => (
 					<div key={ tile.key } className={ clsx( styles.tile, tile.className ) } role="listitem">
-						<div className={ styles.header } title={ tile.note }>
+						<MetricNoteTooltip note={ tile.note } className={ styles.header }>
 							{ tile.icon && <Icon icon={ tile.icon } size={ 20 } className={ styles.icon } /> }
 							<Text className={ styles.label }>{ tile.label }</Text>
-							{ /* The `title` tooltip is invisible to keyboard and screen-reader
-							     users, so the caveat is repeated as visually hidden text. */ }
-							{ tile.note && <VisuallyHidden>{ tile.note }</VisuallyHidden> }
-						</div>
+						</MetricNoteTooltip>
 						<MetricTileValue
 							tile={ tile }
 							dataFormat={ dataFormat }

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/post-highlight-card/__tests__/post-highlight-card.test.tsx

@@ -1,7 +1,8 @@
 /**
  * External dependencies
  */
-import { render, screen } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { getSettings, setSettings } from '@wordpress/date';
 /**
  * Internal dependencies
@@ -36,7 +37,10 @@ const BASE_SETTINGS = getSettings();
 
 describe( 'PostHighlightCard', () => {
 	beforeEach( () => setSettings( EN_US_SETTINGS ) );
-	afterEach( () => setSettings( BASE_SETTINGS ) );
+	afterEach( () => {
+		setSettings( BASE_SETTINGS );
+		jest.useRealTimers();
+	} );
 
 	it( 'links the title to the detail route and carries the report window', () => {
 		render(
@@ -124,13 +128,15 @@ describe( 'PostHighlightCard', () => {
 		expect( screen.getByText( '0' ) ).toBeInTheDocument();
 	} );
 
-	// A lifetime metric shown next to a period-scoped one must say so, and the
-	// `title` tooltip alone is invisible to assistive technology.
-	it( 'exposes a metric note as both a tooltip and visually hidden text', () => {
+	it( 'shows a metric note in a tooltip on the metric label', async () => {
+		jest.useFakeTimers();
+		const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
 		render( <PostHighlightCard { ...props } /> );
 
-		expect( screen.getByTitle( 'All-time total.' ) ).toBeInTheDocument();
-		expect( screen.getByText( 'All-time total.' ) ).toBeInTheDocument();
+		await user.hover( screen.getByText( 'Likes' ) );
+		await act( () => jest.runAllTimersAsync() );
+
+		expect( screen.getByTestId( 'metric-note-tooltip' ) ).toHaveTextContent( 'All-time total.' );
 	} );
 
 	it( 'renders the featured image only when one is present', () => {

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/post-highlight-card/post-highlight-card.module.scss

@@ -123,6 +123,11 @@
 	min-inline-size: 0;
 }
 
+.metricHeader {
+	display: flex;
+	min-inline-size: 0;
+}
+
 .metricLabel {
 	overflow: hidden;
 	color: var(--wpds-color-foreground-content-neutral);

projects/packages/premium-analytics/packages/widgets-toolkit/src/components/post-highlight-card/post-highlight-card.tsx

@@ -8,6 +8,7 @@ import { __, sprintf } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
+import { MetricNoteTooltip } from '../metric-note-tooltip';
 import { MetricValue } from '../metric-value';
 import { PostTitleLink } from '../post-title-link';
 import styles from './post-highlight-card.module.scss';
@@ -40,8 +41,7 @@ export type PostHighlightCardMetric = {
 
 	/**
 	 * Caveat about how the value is aggregated (e.g. an all-time total among
-	 * date-scoped neighbours). Shown as a hover tooltip and mirrored as
-	 * visually hidden text for assistive technology.
+	 * date-scoped neighbours), shown in a tooltip on the label.
 	 */
 	note?: string;
 };
@@ -127,13 +127,12 @@ function PostHighlightMetric( {
 	dataFormat: DataFormat;
 } ) {
 	return (
-		<div className={ styles.metric } title={ metric.note }>
-			<Text className={ styles.metricLabel } variant="body-md">
-				{ metric.label }
-			</Text>
-			{ /* The `title` tooltip is invisible to keyboard and screen-reader users,
-			     so the caveat is repeated as visually hidden text. */ }
-			{ metric.note && <VisuallyHidden>{ metric.note }</VisuallyHidden> }
+		<div className={ styles.metric }>
+			<MetricNoteTooltip note={ metric.note } className={ styles.metricHeader }>
+				<Text className={ styles.metricLabel } variant="body-md">
+					{ metric.label }
+				</Text>
+			</MetricNoteTooltip>
 			{ metric.value === undefined ? (
 				<Text className={ styles.metricValue } variant="body-md">
 					{ /* Spelled out below, since a screen reader may skip the dash. */ }