@automattic/charts 4.13.0 → 4.15.0

package/src/components/legend/test/legend.test.tsx

@@ -900,6 +900,131 @@ describe( 'BaseLegend', () => {
 		} );
 	} );
 
+	describe( 'Controlled items', () => {
+		const VisibilityProbe = () => {
+			const { isSeriesVisible } = useGlobalChartsContext();
+			return (
+				<output data-testid="views-visible">
+					{ String( isSeriesVisible( 'test-chart', 'Views' ) ) }
+				</output>
+			);
+		};
+
+		it.each( [ false, true ] )( 'takes the pressed state from the item (%s)', pressed => {
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed, onToggle: jest.fn() } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			expect( screen.getByRole( 'button', { name: /Previous period/ } ) ).toHaveAttribute(
+				'aria-pressed',
+				String( pressed )
+			);
+		} );
+
+		it.each( [ 'click', 'Enter', ' ' ] )(
+			'calls onToggle on %s and leaves series visibility alone',
+			async interaction => {
+				const user = userEvent.setup();
+				const onToggle = jest.fn();
+				render(
+					<GlobalChartsProvider>
+						<BaseLegend
+							items={ [
+								{
+									label: 'Previous period',
+									color: '#000',
+									seriesLabels: [ 'Views' ],
+									pressed: false,
+									onToggle,
+								},
+							] }
+							interactive
+							chartId="test-chart"
+						/>
+						<VisibilityProbe />
+					</GlobalChartsProvider>
+				);
+
+				const button = screen.getByRole( 'button', { name: /Previous period/ } );
+				if ( interaction === 'click' ) {
+					await user.click( button );
+				} else {
+					button.focus();
+					await user.keyboard( interaction === ' ' ? ' ' : '{Enter}' );
+				}
+
+				expect( onToggle ).toHaveBeenCalledTimes( 1 );
+				expect( onToggle ).toHaveBeenCalledWith();
+				expect( screen.getByTestId( 'views-visible' ) ).toHaveTextContent( 'true' );
+			}
+		);
+
+		it( 'ignores key repeats while Enter is held', async () => {
+			const user = userEvent.setup();
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [ { label: 'Previous period', color: '#000', pressed: false, onToggle } ] }
+						interactive
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+
+			screen.getByRole( 'button', { name: /Previous period/ } ).focus();
+			await user.keyboard( '{Enter>3/}' );
+
+			expect( onToggle ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		const renderStaticControlledItem = ( pressed: boolean ) => {
+			const onToggle = jest.fn();
+			render(
+				<GlobalChartsProvider>
+					<BaseLegend
+						items={ [
+							{
+								label: 'Previous period',
+								color: '#000',
+								seriesLabels: [ 'Views' ],
+								pressed,
+								onToggle,
+							},
+						] }
+						interactive={ false }
+						chartId="test-chart"
+					/>
+				</GlobalChartsProvider>
+			);
+			return { item: screen.getByTestId( 'legend-item' ), onToggle };
+		};
+
+		it( 'stays static in a legend that is not interactive', async () => {
+			const user = userEvent.setup();
+			const { item, onToggle } = renderStaticControlledItem( true );
+
+			expect( screen.queryByRole( 'button' ) ).not.toBeInTheDocument();
+			expect( item ).not.toHaveClass( 'legend-item--inactive' );
+			expect( item ).not.toHaveAttribute( 'aria-label' );
+			await user.click( item );
+			expect( onToggle ).not.toHaveBeenCalled();
+		} );
+
+		it( 'dims an item that is not pressed in a legend that is not interactive', () => {
+			const { item } = renderStaticControlledItem( false );
+
+			expect( item ).toHaveClass( 'legend-item--inactive' );
+			expect( item ).toHaveAttribute( 'aria-label', 'Previous period: hidden' );
+		} );
+	} );
+
 	describe( 'Non-interactive legend reflects hidden state', () => {
 		const HiddenSeriesHarness = ( { interactive }: { interactive: boolean } ) => {
 			const context = useGlobalChartsContext();

package/src/components/legend/types.ts

@@ -65,4 +65,12 @@ export type BaseLegendItem = {
 	interactive?: boolean;
 	/** Label of the series this static item describes; the item is left out while it is hidden. */
 	describesSeries?: string;
-};
+} & (
+	| {
+			/** Pressed state of the toggle. */
+			pressed: boolean;
+			/** Makes an interactive legend item a toggle the consumer controls, instead of a series toggle. */
+			onToggle: () => void;
+	  }
+	| { pressed?: never; onToggle?: never }
+);

package/src/providers/chart-context/themes.ts

@@ -56,6 +56,10 @@ const defaultTheme: CompleteChartTheme = {
 		margin: { top: 2, right: 2, bottom: 2, left: 2 },
 		strokeWidth: 1.5,
 	},
+	compactWhenShort: {
+		below: 140,
+		margin: { top: 2, right: 2, bottom: 2, left: 2 },
+	},
 	// The compact 11px square / 2px gap is the contribution-graph rhythm, which has no WPDS dimension.
 	heatmapChart: {
 		compactCellGap: 2,

package/src/styles/chart-scope.scss

@@ -87,6 +87,7 @@
 
 	--a8c-charts-dimension-leaderboard-row-gap: var(--wpds-dimension-gap-md);
 	--a8c-charts-dimension-leaderboard-column-gap: var(--wpds-dimension-gap-xs);
+	--a8c-charts-dimension-leaderboard-label-inset: var(--wpds-dimension-padding-sm);
 	--a8c-charts-dimension-legend-column-gap: var(--wpds-dimension-gap-lg);
 	--a8c-charts-dimension-legend-row-gap: var(--wpds-dimension-gap-sm);
 }

package/src/types.ts

@@ -214,20 +214,18 @@ type LeaderboardEntryFields = {
 	previousValue?: number;
 
 	/**
-	 * Width of current bar, as % of the largest absolute value across rows. A negative share
-	 * extends the bar from a shared zero point toward the inline start, for every row.
+	 * Width of current bar, as %. Derived from the values when omitted; a passed value wins.
+	 * A negative share extends the bar from a shared zero point toward the inline start, for every row.
 	 */
-	currentShare: number;
+	currentShare?: number;
 
 	/**
-	 * Width of previous bar, as % of the largest absolute value across rows. Omit when this
-	 * row has no matching comparison-period value.
+	 * Width of previous bar, as %. Derived from `previousValue` when omitted; a passed value wins.
 	 */
 	previousShare?: number;
 
 	/**
-	 * Delta of the entry. Omit when the percentage change is unavailable, such
-	 * as when the row has no comparison value or its previous value is zero.
+	 * Percentage change. Derived from the values when omitted; a passed value wins.
 	 */
 	delta?: number;
 
@@ -319,9 +317,9 @@ export type BarStyles = {
 };
 
 /**
- * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot.
+ * How a bar chart places its series in a category. `grouped` puts each primary series in a slot of its own; `overlap` puts every primary in one slot and every comparison in a second, and overlaps the `group`s within each slot; `stacked` stacks every primary in one bar, the first series at the bottom.
  */
-export type BarChartLayout = 'grouped' | 'overlap';
+export type BarChartLayout = 'grouped' | 'overlap' | 'stacked';
 
 export type MultipleDataPointsDate = {
 	label: string;
@@ -439,6 +437,18 @@ export type ChartTheme = {
 		/** Stroke width for the sparkline line */
 		strokeWidth?: number;
 	};
+	/** Compact mode for `compactWhenShort` line, area and bar charts */
+	compactWhenShort?: {
+		/** Height (px) below which the chart turns compact */
+		below?: number;
+		/** Margin the chart defaults to while compact */
+		margin?: {
+			top?: number;
+			right?: number;
+			bottom?: number;
+			left?: number;
+		};
+	};
 	/**
 	 * HeatmapChart settings. Cell gap, radius, value size and the selection ring come from
 	 * WPDS tokens in CSS, so only the compact sizing lives here.
@@ -469,6 +479,9 @@ export type CompleteChartTheme = Required< ChartTheme > & {
 	sparkline: Required< NonNullable< ChartTheme[ 'sparkline' ] > > & {
 		margin: Required< NonNullable< ChartTheme[ 'sparkline' ] >[ 'margin' ] >;
 	};
+	compactWhenShort: Required< NonNullable< ChartTheme[ 'compactWhenShort' ] > > & {
+		margin: Required< NonNullable< ChartTheme[ 'compactWhenShort' ] >[ 'margin' ] >;
+	};
 	heatmapChart: Required< NonNullable< ChartTheme[ 'heatmapChart' ] > >;
 };
 
@@ -522,6 +535,12 @@ export type AxisOptions = {
 	 * so callers can force a specific axis (e.g. integer-only steps on a sparse chart).
 	 */
 	tickValues?: ScaleInput< AxisScale >[];
+	/**
+	 * Most decimal places a value-axis tick may carry, so labels rounded to that precision never repeat;
+	 * an axis holding fewer than two steps widens to the nearest ones. Whole-number data always uses 0.
+	 * Ignored on a log scale, or when `tickValues` or the value scale's `domain` is set. Line and bar charts only.
+	 */
+	tickDecimals?: number;
 	axisClassName?: string;
 	axisLineClassName?: string;
 	labelClassName?: string;
@@ -711,6 +730,18 @@ export interface SeriesVisibilityProps {
 	defaultHiddenSeries?: readonly string[];
 }
 
+/**
+ * Compact mode for cartesian charts placed in short containers.
+ */
+export interface CompactWhenShortProps {
+	/**
+	 * Drop the axes, grid and legend, and default to `theme.compactWhenShort.margin`, while the
+	 * chart is shorter than `theme.compactWhenShort.below`. Series hidden through the legend stay
+	 * hidden until the chart is tall again. Horizontal bar charts ignore it.
+	 */
+	compactWhenShort?: boolean;
+}
+
 /**
  * Base properties shared across all chart components
  */

package/src/charts/private/test/whole-number-ticks.test.tsx

@@ -1,57 +0,0 @@
-import { createScale } from '@visx/scale';
-import { getWholeNumberTickValues, hasOnlyWholeNumbers } from '../whole-number-ticks';
-import type { SeriesData } from '../../../types';
-
-const linear = ( domain: [ number, number ] ) =>
-	createScale( { type: 'linear', domain, range: [ 100, 0 ] } );
-
-const series = ( ...values: Array< number | null > ): SeriesData => ( {
-	label: 'A',
-	data: values.map( ( value, i ) => ( { date: new Date( 2024, i, 1 ), value } ) ),
-} );
-
-describe( 'getWholeNumberTickValues', () => {
-	it( 'keeps only the whole ticks of a range smaller than the tick count', () => {
-		expect( getWholeNumberTickValues( linear( [ 0, 1 ] ), 4 ) ).toEqual( [ 0, 1 ] );
-		expect( getWholeNumberTickValues( linear( [ 0, 2 ] ), 4 ) ).toEqual( [ 0, 1, 2 ] );
-	} );
-
-	it( 'leaves a scale whose ticks are already whole to visx', () => {
-		expect( getWholeNumberTickValues( linear( [ 0, 1000 ] ), 4 ) ).toBeUndefined();
-	} );
-
-	it( 'leaves non-numeric scales to visx', () => {
-		const band = createScale( { type: 'band', domain: [ 'a', 'b' ], range: [ 0, 100 ] } );
-		const time = createScale( {
-			type: 'time',
-			domain: [ new Date( 2024, 0, 1 ), new Date( 2024, 0, 2 ) ],
-			range: [ 0, 100 ],
-		} );
-		expect( getWholeNumberTickValues( band, 4 ) ).toBeUndefined();
-		expect( getWholeNumberTickValues( time, 4 ) ).toBeUndefined();
-		expect( getWholeNumberTickValues( undefined, 4 ) ).toBeUndefined();
-	} );
-
-	it( 'leaves a range with no whole tick to visx', () => {
-		expect( getWholeNumberTickValues( linear( [ 0.2, 0.8 ] ), 4 ) ).toBeUndefined();
-	} );
-
-	it( 'leaves a range with only one whole tick to visx', () => {
-		expect( getWholeNumberTickValues( linear( [ 0, 0.8 ] ), 4 ) ).toBeUndefined();
-	} );
-} );
-
-describe( 'hasOnlyWholeNumbers', () => {
-	it( 'is true when every reading is whole, skipping missing ones', () => {
-		expect( hasOnlyWholeNumbers( [ series( 0, 1, null, 3 ) ] ) ).toBe( true );
-	} );
-
-	it( 'is false when any reading has a fraction', () => {
-		expect( hasOnlyWholeNumbers( [ series( 0, 1 ), series( 0.5 ) ] ) ).toBe( false );
-	} );
-
-	it( 'is false when there is no reading at all', () => {
-		expect( hasOnlyWholeNumbers( [ series( null, null ) ] ) ).toBe( false );
-		expect( hasOnlyWholeNumbers( [] ) ).toBe( false );
-	} );
-} );

package/src/charts/private/whole-number-ticks.tsx

@@ -1,79 +0,0 @@
-import { DataContext } from '@visx/xychart';
-import { useContext } from 'react';
-import { isReading } from './readings';
-import type { SeriesData } from '../../types';
-import type { ReactNode } from 'react';
-
-/**
- * Whether every reading in the series is a whole number.
- *
- * @param series - The series visx renders.
- * @return True when at least one reading exists and none has a fraction.
- */
-export const hasOnlyWholeNumbers = ( series: SeriesData[] ): boolean => {
-	let sawReading = false;
-	for ( const { data } of series ) {
-		for ( const point of data ) {
-			const value = point?.value;
-			if ( ! isReading( value ) ) {
-				continue;
-			}
-			if ( ! Number.isInteger( value ) ) {
-				return false;
-			}
-			sawReading = true;
-		}
-	}
-	return sawReading;
-};
-
-/**
- * The scale's ticks with the fractional ones dropped.
- *
- * d3 steps by 1, 2 or 5 times a power of ten, so every whole number inside the domain is one of its ticks.
- *
- * @param scale - The value scale visx built.
- * @param count - Ticks to ask the scale for; undefined uses the scale's own default, as visx does.
- * @return Whole-number ticks, or undefined when visx's own ticks need no change.
- */
-export const getWholeNumberTickValues = (
-	scale: unknown,
-	count?: number
-): number[] | undefined => {
-	const ticks = ( scale as { ticks?: ( count?: number ) => unknown[] } )?.ticks?.( count );
-	if ( ! ticks?.every( ( tick ): tick is number => typeof tick === 'number' ) ) {
-		return undefined;
-	}
-	const whole = ticks.filter( tick => Number.isInteger( tick ) );
-	return whole.length > 1 && whole.length < ticks.length ? whole : undefined;
-};
-
-type WholeNumberTicksProps = {
-	axis: 'x' | 'y';
-	numTicks?: number;
-	enabled: boolean;
-	children: ( tickValues: number[] | undefined ) => ReactNode;
-};
-
-/**
- * Hands its children the whole-number ticks of the chart's value scale.
- *
- * @param props          - Component props.
- * @param props.axis     - Which scale carries the values.
- * @param props.numTicks - Ticks to ask the scale for.
- * @param props.enabled  - Whether the plotted values are all whole numbers and the caller pinned neither the ticks nor the value domain.
- * @param props.children - Renders the axis and grid with the tick values.
- * @return The rendered children.
- */
-export const WholeNumberTicks = ( {
-	axis,
-	numTicks,
-	enabled,
-	children,
-}: WholeNumberTicksProps ) => {
-	const { xScale, yScale } = useContext( DataContext );
-	const tickValues = enabled
-		? getWholeNumberTickValues( axis === 'x' ? xScale : yScale, numTicks )
-		: undefined;
-	return <>{ children( tickValues ) }</>;
-};