@automattic/charts 1.11.0 → 2.0.0

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

@@ -2,6 +2,7 @@ import { curveCatmullRom, curveLinear, curveMonotoneX } from '@visx/curve';
 import { scaleTime } from '@visx/scale';
 import { differenceInHours, differenceInYears } from 'date-fns';
 import type { useChartDataTransform } from '../../hooks';
+import type { TickResolution } from '../../types';
 import type { CurveType } from '../line-chart/types';
 
 // Approximate min pixel width for an x-axis tick label.
@@ -47,20 +48,98 @@ const formatHourTick = ( timestamp: number ) => {
 	return date.toLocaleTimeString( undefined, { hour: 'numeric', hour12: true } );
 };
 
-// Pick the most informative tick formatter for the data's time span: hours
-// within a day, calendar dates within a year, otherwise just years.
-export const getFormatter = ( sortedData: ReturnType< typeof useChartDataTransform > ) => {
+// Hour ticks with the date at midnight boundaries, so multi-day spans of
+// sub-daily data keep their days identifiable.
+const formatDateOrHourTick = ( timestamp: number ) => {
+	const date = new Date( timestamp );
+	return date.getHours() === 0 && date.getMinutes() === 0
+		? formatDateTick( timestamp )
+		: formatHourTick( timestamp );
+};
+
+// Month ticks with the year at January boundaries, for month-or-coarser
+// buckets where a full "Sep 1" date would misread as a daily point.
+const formatMonthOrYearTick = ( timestamp: number ) => {
+	const date = new Date( timestamp );
+	return date.getMonth() === 0
+		? formatYearTick( timestamp )
+		: date.toLocaleDateString( undefined, { month: 'short' } );
+};
+
+// Smallest interval between consecutive points across all series, in hours.
+// Infinity when no series has two points.
+const getPointSpacingInHours = ( sortedData: ReturnType< typeof useChartDataTransform > ) => {
+	return sortedData.reduce(
+		( spacing, datom ) =>
+			datom.data.reduce( ( seriesSpacing, point, index ) => {
+				const previous = datom.data[ index - 1 ];
+				if ( previous?.date === undefined || point?.date === undefined ) {
+					return seriesSpacing;
+				}
+				return Math.min(
+					seriesSpacing,
+					Math.abs( differenceInHours( point.date, previous.date ) )
+				);
+			}, spacing ),
+		Number.POSITIVE_INFINITY
+	);
+};
+
+// Nominal point spacing for a caller-declared bucket resolution. A month maps
+// to the shortest month so the month-or-coarser regime engages (see
+// getFormatter). Year is absent: it short-circuits to year ticks before the
+// spacing regimes run.
+const SPACING_BY_RESOLUTION: Record< Exclude< TickResolution, 'year' >, number > = {
+	hour: 1,
+	day: 24,
+	week: 24 * 7,
+	month: 28 * 24,
+};
+
+// Pick the most informative tick formatter for the data's resolution and time
+// span: hours within a day, hours with day boundaries for sub-daily data
+// spanning up to a week, calendar dates for daily-or-finer buckets within a
+// year, months (with the year at January) for month-or-coarser buckets,
+// otherwise just years. The resolution comes from `tickResolution` when the
+// caller knows it, and is inferred from point spacing otherwise.
+export const getFormatter = (
+	sortedData: ReturnType< typeof useChartDataTransform >,
+	tickResolution?: TickResolution
+) => {
+	// The month regime only prints the year at January boundaries, so yearly
+	// buckets starting mid-year would render as month names; year ticks are
+	// correct for yearly buckets at any span.
+	if ( tickResolution === 'year' ) {
+		return formatYearTick;
+	}
+
 	const minX = Math.min( ...sortedData.map( datom => datom.data.at( 0 )?.date ) );
 	const maxX = Math.max( ...sortedData.map( datom => datom.data.at( -1 )?.date ) );
 
+	const spacingInHours = tickResolution
+		? SPACING_BY_RESOLUTION[ tickResolution ]
+		: getPointSpacingInHours( sortedData );
+	// 23, not 24: a daily gap shrinks to 23 wall-clock hours across a
+	// spring-forward DST transition.
+	const isSubDaily = spacingInHours < 23;
+
 	const diffInHours = Math.abs( differenceInHours( maxX, minX ) );
-	if ( diffInHours <= 24 ) {
+	if ( diffInHours <= 24 && isSubDaily ) {
 		return formatHourTick;
 	}
 
+	if ( diffInHours <= 24 * 7 && isSubDaily ) {
+		return formatDateOrHourTick;
+	}
+
 	const diffInYears = Math.abs( differenceInYears( maxX, minX ) );
 	if ( diffInYears <= 1 ) {
-		return formatDateTick;
+		// 28 days: the shortest month, so monthly buckets qualify but weekly
+		// don't. The finiteness check keeps all-single-point series — whose
+		// resolution is unknowable — on date ticks.
+		return Number.isFinite( spacingInHours ) && spacingInHours >= 28 * 24
+			? formatMonthOrYearTick
+			: formatDateTick;
 	}
 
 	return formatYearTick;

package/src/charts/private/x-zoom/index.ts

@@ -0,0 +1 @@
+export { useXZoom, ZoomClip, ZoomResetButton, ZoomSelectionRect } from './x-zoom';

package/src/charts/private/{test → x-zoom/test}/x-zoom.test.tsx

@@ -1,8 +1,10 @@
-import { act, renderHook } from '@testing-library/react';
-import { useRef } from 'react';
-import { useXZoom } from '../x-zoom';
-import type { SingleChartRef } from '../single-chart-context';
+import { act, render, renderHook, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useCallback, useRef, useState } from 'react';
+import { useXZoom, ZoomResetButton } from '../index';
+import type { SingleChartRef } from '../../single-chart-context';
 import type { EventHandlerParams } from '@visx/xychart';
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
 
 // A fake scale that lets the hook convert pixel positions to data values.
 // The hook only uses `.invert()`; everything else can be stubbed.
@@ -140,3 +142,89 @@ describe( 'useXZoom', () => {
 		expect( result.current.domain ).toBeNull();
 	} );
 } );
+
+const preventDefaultKeydown = ( event: ReactKeyboardEvent< HTMLDivElement > ) =>
+	event.preventDefault();
+
+describe( 'ZoomResetButton', () => {
+	test( 'renders a labelled button without a native title tooltip', () => {
+		const noop = jest.fn();
+		render( <ZoomResetButton onClick={ noop } /> );
+		const button = screen.getByTestId( 'chart-zoom-reset' );
+		expect( button.tagName ).toBe( 'BUTTON' );
+		expect( button ).toHaveClass( 'x-zoom__reset' );
+		expect( button ).toHaveAccessibleName( 'Reset zoom' );
+		// IconButton renders a real tooltip, so the `title` fallback is gone —
+		// `title` is invisible to keyboard users and cannot be dismissed.
+		expect( button ).not.toHaveAttribute( 'title' );
+	} );
+
+	test( 'shows a tooltip on keyboard focus', async () => {
+		const noop = jest.fn();
+		render( <ZoomResetButton onClick={ noop } /> );
+		await userEvent.tab();
+		expect( screen.getByTestId( 'chart-zoom-reset' ) ).toHaveFocus();
+		// The button's only text is the tooltip's — its own label is an
+		// `aria-label` attribute, so this cannot match the trigger.
+		await expect( screen.findByText( 'Reset zoom' ) ).resolves.toBeVisible();
+	} );
+
+	test( 'dismisses the tooltip on Escape', async () => {
+		const noop = jest.fn();
+		render( <ZoomResetButton onClick={ noop } /> );
+		await userEvent.tab();
+		await expect( screen.findByText( 'Reset zoom' ) ).resolves.toBeVisible();
+		await userEvent.keyboard( '{Escape}' );
+		await waitFor( () => expect( screen.queryByText( 'Reset zoom' ) ).not.toBeInTheDocument() );
+	} );
+
+	test( 'fires onClick when activated', async () => {
+		const onClick = jest.fn();
+		render( <ZoomResetButton onClick={ onClick } /> );
+		await userEvent.click( screen.getByTestId( 'chart-zoom-reset' ) );
+		expect( onClick ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	test( 'leaves no orphaned tooltip when activation unmounts the button', async () => {
+		// Resetting the zoom unmounts this control while its tooltip is open.
+		// The tooltip renders in a portal outside the container, so a missed
+		// cleanup would strand it on the page rather than remove it with the
+		// button.
+		/**
+		 * Mirrors the host charts: the reset control exists only while zoomed.
+		 *
+		 * @return JSX element or null.
+		 */
+		function Host() {
+			const [ zoomed, setZoomed ] = useState( true );
+			const unzoom = useCallback( () => setZoomed( false ), [] );
+			return zoomed ? <ZoomResetButton onClick={ unzoom } /> : null;
+		}
+		render( <Host /> );
+		await userEvent.tab();
+		await expect( screen.findByText( 'Reset zoom' ) ).resolves.toBeVisible();
+
+		await userEvent.keyboard( '{Enter}' );
+
+		await waitFor( () =>
+			expect( screen.queryByTestId( 'chart-zoom-reset' ) ).not.toBeInTheDocument()
+		);
+		expect( document.body ).not.toHaveTextContent( 'Reset zoom' );
+	} );
+
+	test( 'keyboard activation survives the chart wrapper keydown handler', async () => {
+		const onClick = jest.fn();
+		// Mirrors the chart's grid wrapper, 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 }>
+				<ZoomResetButton onClick={ onClick } />
+			</div>
+		);
+		act( () => screen.getByTestId( 'chart-zoom-reset' ).focus() );
+		await userEvent.keyboard( '{Enter}' );
+		await userEvent.keyboard( ' ' );
+		expect( onClick ).toHaveBeenCalledTimes( 2 );
+	} );
+} );

package/src/charts/private/x-zoom/x-zoom.module.scss

@@ -0,0 +1,35 @@
+.x-zoom {
+
+	// The selection's translucency lives in the SVG opacity properties so
+	// the colors themselves can come straight from WPDS tokens.
+	&__selection {
+		fill: var(--a8c-charts-color-zoom-selection, var(--wpds-color-background-interactive-brand-strong, #3858e9));
+		fill-opacity: 0.16;
+		stroke: var(--a8c-charts-color-zoom-selection-stroke, var(--wpds-color-stroke-interactive-brand, #3858e9));
+		stroke-opacity: 0.65;
+		stroke-width: var(--wpds-border-width-xs, 1px);
+		pointer-events: none;
+	}
+
+	// The elevation shadow is deliberately kept for separation
+	// from chart content (CHARTS-237 design call, carrying
+	// over CHARTS-200's tokenization). `@wordpress/theme` 1.0.0
+	// dropped the `--wpds-elevation-*` group, so this role carries
+	// the former token's spec value directly rather than nesting
+	// a `--wpds-*` var.
+	&__reset {
+		position: absolute;
+		top: var(--wpds-dimension-gap-sm, 8px);
+		right: var(--wpds-dimension-gap-sm, 8px);
+		z-index: 2;
+		box-shadow: var(--a8c-charts-elevation-xs, 0 1px 1px 0 #00000008, 0 1px 2px 0 #00000005, 0 3px 3px 0 #00000005, 0 4px 4px 0 #00000003);
+
+		// WPDS outline-neutral is transparent-bodied at rest; give this
+		// floating control an opaque body so chart content doesn't show
+		// through it. Scoped to the rest state so the WPDS
+		// hover/active/focus backgrounds still apply.
+		&:not(:hover, :active, :focus) {
+			background-color: var(--a8c-charts-color-background, var(--wpds-color-background-surface-neutral-strong, #fff));
+		}
+	}
+}

package/src/charts/private/{x-zoom.tsx → x-zoom/x-zoom.tsx}

@@ -1,11 +1,12 @@
 import { DataContext } from '@visx/xychart';
 import { __ } from '@wordpress/i18n';
+import { IconButton } from '@wordpress/ui';
 import { useCallback, useContext, useMemo, useState } from 'react';
 import styles from './x-zoom.module.scss';
-import type { SingleChartRef } from './single-chart-context';
+import type { SingleChartRef } from '../single-chart-context';
 import type { AxisScale } from '@visx/axis';
 import type { EventHandlerParams } from '@visx/xychart';
-import type { ReactNode, RefObject } from 'react';
+import type { KeyboardEvent, ReactNode, RefObject } from 'react';
 
 const MIN_DRAG_PIXELS = 6;
 
@@ -170,40 +171,56 @@ export function ZoomClip( {
 }
 
 /**
- * Visible icon-only reset button rendered as an HTML overlay on top of
- * the chart container. The host should wrap its SVG in a `position: relative`
- * container so the button anchors correctly.
+ * Visible icon-only reset control rendered as an HTML overlay on top of the
+ * chart container, using the WPDS `IconButton`. The host should wrap its SVG in
+ * a `position: relative` container so the button anchors correctly.
  *
  * @param props         - Props.
  * @param props.onClick - Click handler. Typically the `reset` from `useXZoom`.
  * @return JSX element.
  */
 export function ZoomResetButton( { onClick }: { onClick: () => void } ) {
-	const label = __( 'Reset zoom', 'jetpack-charts' );
+	// The chart's keyboard-navigation wrapper calls preventDefault() on
+	// bubbled keydowns, which would cancel the native Enter/Space button
+	// activation. Keep activation keys out of its reach.
+	const stopActivationKeys = useCallback( ( event: KeyboardEvent< HTMLButtonElement > ) => {
+		if ( event.key === 'Enter' || event.key === ' ' ) {
+			event.stopPropagation();
+		}
+	}, [] );
 	return (
-		<button
-			type="button"
+		<IconButton
 			className={ styles[ 'x-zoom__reset' ] }
+			onKeyDown={ stopActivationKeys }
+			label={ __( 'Reset zoom', 'jetpack-charts' ) }
+			variant="outline"
+			tone="neutral"
+			size="small"
 			onClick={ onClick }
-			aria-label={ label }
-			title={ label }
 			data-testid="chart-zoom-reset"
-		>
-			<svg
-				className={ styles[ 'x-zoom__reset-icon' ] }
-				viewBox="0 0 24 24"
-				fill="none"
-				stroke="currentColor"
-				strokeWidth="2"
-				strokeLinecap="round"
-				strokeLinejoin="round"
-				aria-hidden="true"
-				focusable="false"
-			>
-				<circle cx="10" cy="10" r="6" />
-				<line x1="15" y1="15" x2="20" y2="20" />
-				<line x1="7" y1="10" x2="13" y2="10" />
-			</svg>
-		</button>
+			icon={
+				<svg
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					strokeWidth="2"
+					strokeLinecap="round"
+					strokeLinejoin="round"
+					aria-hidden="true"
+					focusable="false"
+				>
+					{ /*
+						Icons render edge-to-edge at 24px, so inset the glyph the
+						way @wordpress/icons glyphs do (drawn within roughly 4-20
+						of the viewBox, ~1.5px effective stroke).
+					*/ }
+					<g transform="translate(2.4 2.4) scale(0.8)">
+						<circle cx="10" cy="10" r="6" />
+						<line x1="15" y1="15" x2="20" y2="20" />
+						<line x1="7" y1="10" x2="13" y2="10" />
+					</g>
+				</svg>
+			}
+		/>
 	);
 }

package/src/components/legend/hooks/test/use-chart-legend-items.test.tsx

@@ -265,4 +265,156 @@ describe( 'useChartLegendItems', () => {
 			expect( result.current[ 0 ].color ).toBeDefined();
 		} );
 	} );
+
+	describe( 'Group collapsing (SeriesData)', () => {
+		const groupedComparisonData: SeriesData[] = [
+			{ label: 'Views', group: 'views', data: [ { label: 'Mon', value: 100 } ] },
+			{
+				label: 'Views — previous',
+				group: 'views',
+				options: { type: 'comparison' as const },
+				data: [ { label: 'Mon', value: 90 } ],
+			},
+			{ label: 'Visitors', group: 'visitors', data: [ { label: 'Mon', value: 50 } ] },
+			{
+				label: 'Visitors — previous',
+				group: 'visitors',
+				options: { type: 'comparison' as const },
+				data: [ { label: 'Mon', value: 45 } ],
+			},
+		];
+
+		describe( 'by default', () => {
+			test( 'keeps one item per series for a comparison group', () => {
+				const { result } = renderHook( () => useChartLegendItems( groupedComparisonData ), {
+					wrapper,
+				} );
+
+				expect( result.current ).toHaveLength( 4 );
+				expect( result.current.map( item => item.label ) ).toEqual( [
+					'Views',
+					'Views — previous',
+					'Visitors',
+					'Visitors — previous',
+				] );
+			} );
+
+			test( 'gives each item only its own series label', () => {
+				const { result } = renderHook( () => useChartLegendItems( groupedComparisonData ), {
+					wrapper,
+				} );
+
+				expect( result.current.map( item => item.seriesLabels ) ).toEqual( [
+					[ 'Views' ],
+					[ 'Views — previous' ],
+					[ 'Visitors' ],
+					[ 'Visitors — previous' ],
+				] );
+			} );
+
+			test( 'preserves the original series order for interleaved groups', () => {
+				// `group` predates collapsing and was used for colour coordination, so existing
+				// charts may interleave grouped series. The default legend must not reorder them.
+				const interleaved: SeriesData[] = [
+					{ label: 'Views', group: 'views', data: [ { label: 'Mon', value: 100 } ] },
+					{ label: 'Visitors', group: 'visitors', data: [ { label: 'Mon', value: 50 } ] },
+					{
+						label: 'Views — previous',
+						group: 'views',
+						options: { type: 'comparison' as const },
+						data: [ { label: 'Mon', value: 90 } ],
+					},
+					{
+						label: 'Visitors — previous',
+						group: 'visitors',
+						options: { type: 'comparison' as const },
+						data: [ { label: 'Mon', value: 45 } ],
+					},
+				];
+
+				const { result } = renderHook( () => useChartLegendItems( interleaved ), { wrapper } );
+
+				expect( result.current.map( item => item.label ) ).toEqual( [
+					'Views',
+					'Visitors',
+					'Views — previous',
+					'Visitors — previous',
+				] );
+			} );
+		} );
+
+		describe( 'with collapseGroups enabled', () => {
+			const collapsed = () =>
+				renderHook( () => useChartLegendItems( groupedComparisonData, { collapseGroups: true } ), {
+					wrapper,
+				} );
+
+			test( 'collapses series that share a group into one item per group', () => {
+				const { result } = collapsed();
+
+				expect( result.current ).toHaveLength( 2 );
+			} );
+
+			test( 'uses the primary (non-comparison) series label for the grouped item', () => {
+				const { result } = collapsed();
+
+				expect( result.current[ 0 ].label ).toBe( 'Views' );
+				expect( result.current[ 1 ].label ).toBe( 'Visitors' );
+			} );
+
+			test( 'exposes all member series labels via seriesLabels, primary first', () => {
+				const { result } = collapsed();
+
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'Views', 'Views — previous' ] );
+				expect( result.current[ 1 ].seriesLabels ).toEqual( [ 'Visitors', 'Visitors — previous' ] );
+			} );
+
+			test( 'collapses a shared group that has no comparison series', () => {
+				const sharedGroupNoComparison: SeriesData[] = [
+					{ label: 'A', group: 'metrics', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'B', group: 'metrics', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( sharedGroupNoComparison, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 1 );
+				expect( result.current[ 0 ].label ).toBe( 'A' );
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'A', 'B' ] );
+			} );
+
+			test( 'does not collapse series with distinct group values', () => {
+				const distinctGroups: SeriesData[] = [
+					{ label: 'A', group: 'a', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'B', group: 'b', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( distinctGroups, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 2 );
+				expect( result.current.map( item => item.label ) ).toEqual( [ 'A', 'B' ] );
+			} );
+
+			test( 'leaves ungrouped series as individual items with their own seriesLabels', () => {
+				const ungrouped: SeriesData[] = [
+					{ label: 'One', data: [ { label: 'x', value: 1 } ] },
+					{ label: 'Two', data: [ { label: 'x', value: 2 } ] },
+				];
+
+				const { result } = renderHook(
+					() => useChartLegendItems( ungrouped, { collapseGroups: true } ),
+					{ wrapper }
+				);
+
+				expect( result.current ).toHaveLength( 2 );
+				expect( result.current[ 0 ].seriesLabels ).toEqual( [ 'One' ] );
+				expect( result.current[ 1 ].seriesLabels ).toEqual( [ 'Two' ] );
+			} );
+		} );
+	} );
 } );