@automattic/charts 4.14.0 → 4.15.0

package/src/charts/private/tick-decimals.tsx

@@ -0,0 +1,132 @@
+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;
+};
+
+// Float error in tick * 10^decimals grows with the value, e.g. 0.07 * 100 = 7.000000000000001.
+const EPSILON = 1e-12;
+const tolerance = ( scaled: number ): number => EPSILON * Math.max( 1, Math.abs( scaled ) );
+
+const isValidDecimals = ( decimals: number | undefined ): decimals is number =>
+	Number.isInteger( decimals ) && ( decimals as number ) >= 0;
+
+const isOnDecimals = ( value: number, decimals: number ): boolean => {
+	const scaled = value * 10 ** decimals;
+	return Math.abs( scaled - Math.round( scaled ) ) < tolerance( scaled );
+};
+
+/**
+ * The scale's ticks with those finer than `decimals` places dropped.
+ *
+ * d3 steps by 1, 2 or 5 times a power of ten, so every multiple of 10^-decimals 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.
+ * @param decimals - Decimal places a tick may carry; 0 keeps whole numbers.
+ * @return The kept ticks, or undefined when visx's own ticks need no change.
+ */
+export const getTickDecimalValues = (
+	scale: unknown,
+	count?: number,
+	decimals = 0
+): 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 kept = ticks.filter( tick => isOnDecimals( tick, decimals ) );
+	return kept.length > 1 && kept.length < ticks.length ? kept : undefined;
+};
+
+/**
+ * A value domain widened to the nearest `decimals` steps when fewer than two fit inside it, so the axis shows at least two ticks.
+ *
+ * @param domain   - The domain the chart would scale to.
+ * @param decimals - The axis's `tickDecimals`.
+ * @return The widened domain, or undefined when `domain` needs no change.
+ */
+export const getTickDecimalsDomain = (
+	domain: [ number, number ] | null | undefined,
+	decimals: number | undefined
+): [ number, number ] | undefined => {
+	if ( ! domain || ! isValidDecimals( decimals ) ) {
+		return undefined;
+	}
+	const scale = 10 ** decimals;
+	const low = domain[ 0 ] * scale;
+	const high = domain[ 1 ] * scale;
+	if ( Math.floor( high + tolerance( high ) ) - Math.ceil( low - tolerance( low ) ) >= 1 ) {
+		return undefined;
+	}
+	const floor = Math.floor( low + tolerance( low ) );
+	// Keeps one step when float noise rounds both ends to the same value.
+	const ceil = Math.max( Math.ceil( high - tolerance( high ) ), floor + 1 );
+	return [ floor / scale, ceil / scale ];
+};
+
+/**
+ * The decimals a value axis's ticks are held to: 0 for whole-number data, else the caller's `tickDecimals`.
+ *
+ * @param hasWholeNumberValues - Whether every plotted value is a whole number.
+ * @param tickDecimals         - The axis's `tickDecimals`.
+ * @return Decimal places, or undefined to keep visx's ticks.
+ */
+export const getTickDecimals = (
+	hasWholeNumberValues: boolean,
+	tickDecimals: number | undefined
+): number | undefined => {
+	if ( hasWholeNumberValues ) {
+		return 0;
+	}
+	return isValidDecimals( tickDecimals ) ? tickDecimals : undefined;
+};
+
+type TickDecimalsProps = {
+	axis: 'x' | 'y';
+	numTicks?: number;
+	decimals: number | undefined;
+	children: ( tickValues: number[] | undefined ) => ReactNode;
+};
+
+/**
+ * Hands its children the chart's value-scale ticks, held to `decimals` places.
+ *
+ * @param props          - Component props.
+ * @param props.axis     - Which scale carries the values.
+ * @param props.numTicks - Ticks to ask the scale for.
+ * @param props.decimals - Decimal places a tick may carry, or undefined to keep visx's ticks.
+ * @param props.children - Renders the axis and grid with the tick values.
+ * @return The rendered children.
+ */
+export const TickDecimals = ( { axis, numTicks, decimals, children }: TickDecimalsProps ) => {
+	const { xScale, yScale } = useContext( DataContext );
+	const tickValues =
+		decimals === undefined
+			? undefined
+			: getTickDecimalValues( axis === 'x' ? xScale : yScale, numTicks, decimals );
+	return <>{ children( tickValues ) }</>;
+};

package/src/charts/private/use-compact-when-short.ts

@@ -0,0 +1,18 @@
+import { useGlobalChartsTheme } from '../../providers';
+
+/**
+ * Whether a `compactWhenShort` chart is compact, and the margin it then defaults to.
+ *
+ * Reads the height the chart was given, not the measured plot area: that grows once the legend
+ * is hidden and would flip the chart straight back. A zero height is unmeasured, not short.
+ *
+ * @param enabled - The chart's `compactWhenShort` prop.
+ * @param height  - The height the chart was given.
+ * @return Whether the chart is compact, and the compact margin when it is.
+ */
+export const useCompactWhenShort = ( enabled: boolean, height: number | undefined ) => {
+	const { compactWhenShort } = useGlobalChartsTheme();
+	const isCompact = enabled && ( height ?? 0 ) > 0 && height < compactWhenShort.below;
+
+	return { isCompact, compactMargin: isCompact ? compactWhenShort.margin : undefined };
+};

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/types.ts

@@ -317,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;
@@ -437,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.
@@ -467,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' ] > >;
 };
 
@@ -520,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;
@@ -709,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 ) }</>;
-};