@automattic/charts 1.6.0 → 1.8.0

package/src/types.ts

@@ -1,20 +1,102 @@
-import type { CircleSubjectProps } from '@visx/annotation/lib/components/CircleSubject';
-import type { ConnectorProps } from '@visx/annotation/lib/components/Connector';
-import type { LabelProps } from '@visx/annotation/lib/components/Label';
-import type { LineSubjectProps } from '@visx/annotation/lib/components/LineSubject';
+import type {
+	CircleSubjectProps,
+	ConnectorProps,
+	LabelProps,
+	LineSubjectProps,
+} from '@visx/annotation';
 import type { AxisScale, Orientation, TickFormatter, AxisRendererProps } from '@visx/axis';
-import type { LegendShape } from '@visx/legend/lib/types';
 import type { ScaleInput, ScaleType } from '@visx/scale';
-import type { TextProps } from '@visx/text/lib/Text';
+import type { TextProps } from '@visx/text';
 import type { EventHandlerParams, GlyphProps, GridStyles, LineStyles } from '@visx/xychart';
-import type { GapSize } from '@wordpress/theme';
-import type { CSSProperties, MouseEvent, PointerEvent, ReactNode } from 'react';
-import type { GoogleDataTableColumn, GoogleDataTableRow } from 'react-google-charts';
+import type {
+	ComponentClass,
+	CSSProperties,
+	FC,
+	MouseEvent,
+	PointerEvent,
+	ReactElement,
+	ReactNode,
+} from 'react';
 
 type ValueOf< T > = T[ keyof T ];
 
 export type Optional< T, K extends keyof T > = Pick< Partial< T >, K > & Omit< T, K >;
 
+/**
+ * Mirrors the WordPress Design System gap token scale used by the WordPress UI Stack.
+ */
+export type GapSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+
+export type LegendShapeLabel< Data, Output, ExtraAttributes = object > = {
+	datum: Data;
+	index: number;
+	text: string;
+	value?: Output;
+} & ExtraAttributes;
+
+export type LegendShapeRenderProps< Data, Output > = {
+	width?: string | number;
+	height?: string | number;
+	label: LegendShapeLabel< Data, Output >;
+	item: Data;
+	itemIndex: number;
+	fill?: string;
+	size?: string | number;
+	style?: CSSProperties;
+};
+
+export type LegendShape< Data, Output > =
+	| 'rect'
+	| 'circle'
+	| 'line'
+	| FC< LegendShapeRenderProps< Data, Output > >
+	| ComponentClass< LegendShapeRenderProps< Data, Output > >;
+
+export type GoogleDataTableColumnType =
+	| 'string'
+	| 'number'
+	| 'boolean'
+	| 'date'
+	| 'datetime'
+	| 'timeofday';
+
+export enum GoogleDataTableColumnRoleType {
+	annotation = 'annotation',
+	annotationText = 'annotationText',
+	certainty = 'certainty',
+	emphasis = 'emphasis',
+	interval = 'interval',
+	scope = 'scope',
+	style = 'style',
+	tooltip = 'tooltip',
+	domain = 'domain',
+}
+
+export type GoogleDataTableColumn =
+	| {
+			type: GoogleDataTableColumnType;
+			label?: string;
+			role?: GoogleDataTableColumnRoleType;
+			pattern?: string;
+			p?: Record< string, unknown >;
+			id?: string;
+	  }
+	| string;
+
+export type GoogleDataTableCell =
+	| {
+			v?: unknown;
+			f?: string;
+			p?: Record< string, unknown >;
+	  }
+	| string
+	| number
+	| boolean
+	| Date
+	| null;
+
+export type GoogleDataTableRow = GoogleDataTableCell[];
+
 export type ChartType =
 	| 'area'
 	| 'bar'
@@ -101,7 +183,7 @@ export type LeaderboardEntry = {
 	/**
 	 * Human-readable name (e.g., 'Direct') or a JSX element (e.g., <h4>Direct</h4>)
 	 */
-	label: string | JSX.Element;
+	label: string | ReactElement;
 
 	/**
 	 * Value of the entry
@@ -146,6 +228,17 @@ export type LeaderboardEntry = {
 	 * never both, since interactive elements cannot be nested in HTML.
 	 */
 	onClick?: ( event: MouseEvent< HTMLButtonElement > ) => void;
+
+	/**
+	 * Optional accessible name for the interactive row's `<button>`. Only applies
+	 * when `onClick` is set — without it the row renders as a Fragment with no
+	 * element to receive `aria-label`. By default the button derives its name from
+	 * its rendered content (label text plus the formatted value), which is the
+	 * right outcome for plain-text labels. Set this when the `label` is JSX whose
+	 * text content does not yield a clean name on its own — e.g. an image-only
+	 * label — to give assistive tech a deterministic, human-readable name.
+	 */
+	ariaLabel?: string;
 };
 
 export type GradientStop = {
@@ -175,6 +268,16 @@ export type SeriesData = {
 	options?: SeriesDataOptions;
 };
 
+/**
+ * Visual styling for a bar series of a given semantic type (e.g. 'comparison').
+ * `widthFactor` is the bar width relative to the primary bar slot (1.5 = 150%);
+ * `opacity` sets the shadow translucency.
+ */
+export type BarStyles = {
+	widthFactor?: number;
+	opacity?: number;
+};
+
 export type MultipleDataPointsDate = {
 	label: string;
 	data: DataPointDate[];
@@ -273,7 +376,7 @@ export type ChartTheme = {
 		/** Gap between columns in the leaderboard grid */
 		columnGap?: number;
 		/** Spacing between label and progress bars */
-		labelSpacing?: number;
+		labelSpacing?: GapSize;
 		/** Primary color for current period bars */
 		primaryColor?: string;
 		/** Secondary color for comparison period bars */
@@ -295,6 +398,9 @@ export type ChartTheme = {
 	lineChart?: {
 		lineStyles?: Partial< Record< NonNullable< SeriesDataOptions[ 'type' ] >, LineStyles > >;
 	};
+	barChart?: {
+		barStyles?: Partial< Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles > >;
+	};
 	/** Sparkline specific settings */
 	sparkline?: {
 		/** Margin around the sparkline chart */
@@ -327,6 +433,9 @@ export type CompleteChartTheme = Required< ChartTheme > & {
 	lineChart: {
 		lineStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, LineStyles >;
 	};
+	barChart: {
+		barStyles: Record< NonNullable< SeriesDataOptions[ 'type' ] >, BarStyles >;
+	};
 	legend: Required< NonNullable< ChartTheme[ 'legend' ] > >;
 	sparkline: Required< NonNullable< ChartTheme[ 'sparkline' ] > > & {
 		margin: Required< NonNullable< ChartTheme[ 'sparkline' ] >[ 'margin' ] >;

package/src/utils/get-styles.ts

@@ -1,5 +1,4 @@
-import type { ChartTheme, SeriesData } from '../types';
-import type { LegendShape } from '@visx/legend/lib/types';
+import type { BarStyles, ChartTheme, LegendShape, SeriesData } from '../types';
 import type { LineStyles } from '@visx/xychart';
 
 /**
@@ -29,6 +28,25 @@ export function getSeriesLineStyles(
 	);
 }
 
+/**
+ * Utility to get consolidated bar styles for a series by semantic type.
+ * Mirrors getSeriesLineStyles: a series with `options.type` (e.g. 'comparison')
+ * resolves to `theme.barChart.barStyles[ type ]`.
+ *
+ * @param {SeriesData} seriesData    - The series data containing styling options
+ * @param {number}     index         - The index of the series in the data array
+ * @param {ChartTheme} providerTheme - The chart theme configuration
+ * @return {BarStyles} The consolidated bar styles for the series
+ */
+export function getSeriesBarStyles(
+	seriesData: SeriesData,
+	index: number,
+	providerTheme: ChartTheme
+): BarStyles {
+	const type = seriesData.options?.type;
+	return ( type && providerTheme?.barChart?.barStyles?.[ type ] ) ?? {};
+}
+
 /**
  * Utility function to get stroke color for a series
  *
@@ -62,22 +80,26 @@ export function getItemShapeStyles(
 ): Record< string, unknown > {
 	const seriesShapeStyles = series.options?.legendShapeStyle ?? {};
 	const lineStyles = legendShape === 'line' ? getSeriesLineStyles( series, index, theme ) : {};
+	// For non-line legends (e.g. bar 'rect'), reflect the comparison bar's opacity on the
+	// swatch so the legend marker matches the translucent comparison bar. Line-type legends
+	// convey comparison via the dashed stroke (lineStyles) instead.
+	const barOpacity =
+		legendShape !== 'line' ? getSeriesBarStyles( series, index, theme ).opacity : undefined;
+	const barShapeStyles = barOpacity !== undefined ? { opacity: barOpacity } : {};
 	const themeShapeStyles = theme.legend?.shapeStyles?.[ index ];
 
-	const itemShapeStyles = {
+	// Series-level styles (custom shape style + line styles) take precedence; otherwise fall
+	// back to the per-index theme shape styles.
+	const explicitStyles = {
 		...seriesShapeStyles,
 		...lineStyles,
 	};
+	const hasExplicitStyles = Object.values( explicitStyles ).some(
+		value => value !== undefined && value !== null && value !== ''
+	);
+	const baseShapeStyles = hasExplicitStyles ? explicitStyles : themeShapeStyles ?? {};
 
-	// Return item shape styles if they are not empty
-	if (
-		Object.values( itemShapeStyles ).some(
-			value => value !== undefined && value !== null && value !== ''
-		)
-	) {
-		return itemShapeStyles;
-	}
-
-	// Fallback to theme shape styles if defined
-	return themeShapeStyles ?? {};
+	// Layer the comparison bar opacity on top so the swatch matches the translucent bar
+	// without discarding the base (custom or theme) shape styles.
+	return { ...baseShapeStyles, ...barShapeStyles };
 }

package/src/utils/index.ts

@@ -13,7 +13,12 @@ export { formatPercentage } from './format-percentage';
 export { getLongestTickWidth } from './get-longest-tick-width';
 
 // Style and theming utilities
-export { getSeriesLineStyles, getSeriesStroke, getItemShapeStyles } from './get-styles';
+export {
+	getSeriesBarStyles,
+	getSeriesLineStyles,
+	getSeriesStroke,
+	getItemShapeStyles,
+} from './get-styles';
 
 // Browser detection utilities
 export { isSafari } from './is-safari';

package/src/utils/test/get-styles.test.ts

@@ -1,5 +1,10 @@
 import { ChartTheme } from '../../types';
-import { getSeriesLineStyles, getSeriesStroke, getItemShapeStyles } from '../get-styles';
+import {
+	getSeriesBarStyles,
+	getSeriesLineStyles,
+	getSeriesStroke,
+	getItemShapeStyles,
+} from '../get-styles';
 
 describe( 'Series styling utility functions', () => {
 	const mockSeriesData = {
@@ -157,6 +162,28 @@ describe( 'Series styling utility functions', () => {
 			expect( result ).toEqual( mockTheme.legend.shapeStyles[ 0 ] );
 		} );
 
+		it( 'applies the comparison bar opacity to the swatch for non-line legends', () => {
+			const themeWithBar = {
+				...mockTheme,
+				barChart: { barStyles: { comparison: { widthFactor: 1.5, opacity: 0.5 } } },
+				// No per-index legend shape styles, so the swatch reflects only the comparison opacity.
+				legend: { shapeStyles: [] },
+			} as ChartTheme;
+			const comparisonSeries = {
+				...mockSeriesData,
+				options: { type: 'comparison' as const },
+			};
+
+			// rect (bar) legend: swatch picks up the comparison opacity to match the bar.
+			const rectResult = getItemShapeStyles( comparisonSeries, 0, themeWithBar, 'rect' );
+			expect( rectResult ).toEqual( { opacity: 0.5 } );
+
+			// line legend: comparison is conveyed via the dashed stroke, not opacity.
+			const lineResult = getItemShapeStyles( comparisonSeries, 0, themeWithBar, 'line' );
+			expect( lineResult.opacity ).toBeUndefined();
+			expect( lineResult ).toMatchObject( { strokeDasharray: '4 4' } );
+		} );
+
 		it( 'merges custom shape styles with line styles for line shape', () => {
 			const customShapeStyle = { fill: '#CUSTOM' };
 			const comparisonSeries = {
@@ -330,4 +357,23 @@ describe( 'Series styling utility functions', () => {
 			} );
 		} );
 	} );
+
+	describe( 'getSeriesBarStyles', () => {
+		const themeWithBar = {
+			...mockTheme,
+			barChart: { barStyles: { comparison: { widthFactor: 1.5, opacity: 0.5 } } },
+		} as ChartTheme;
+
+		it( 'returns comparison bar styles when type is comparison', () => {
+			const comparisonSeries = { ...mockSeriesData, options: { type: 'comparison' as const } };
+			expect( getSeriesBarStyles( comparisonSeries, 0, themeWithBar ) ).toEqual( {
+				widthFactor: 1.5,
+				opacity: 0.5,
+			} );
+		} );
+
+		it( 'returns empty styles for a series with no type', () => {
+			expect( getSeriesBarStyles( mockSeriesData, 0, themeWithBar ) ).toEqual( {} );
+		} );
+	} );
 } );

package/src/visx/types.ts

@@ -1,2 +1,31 @@
-export type { RenderTooltipParams } from '@visx/xychart/lib/components/Tooltip';
+import type { PickD3Scale } from '@visx/scale';
+import type { TooltipProps as VisxTooltipProps, UseTooltipPortalOptions } from '@visx/tooltip';
+import type { GlyphProps, TooltipContextType } from '@visx/xychart';
+import type { ReactNode, SVGProps } from 'react';
+
+export type RenderTooltipParams< Datum extends object > = TooltipContextType< Datum > & {
+	colorScale?: PickD3Scale< 'ordinal', string, string >;
+};
+
+export interface RenderTooltipGlyphProps< Datum extends object > extends GlyphProps< Datum > {
+	glyphStyle?: SVGProps< SVGCircleElement >;
+	isNearestDatum: boolean;
+}
+
+export type XyChartTooltipProps< Datum extends object > = {
+	renderTooltip: ( params: RenderTooltipParams< Datum > ) => ReactNode;
+	renderGlyph?: ( params: RenderTooltipGlyphProps< Datum > ) => ReactNode;
+	snapTooltipToDatumX?: boolean;
+	snapTooltipToDatumY?: boolean;
+	showVerticalCrosshair?: boolean;
+	showHorizontalCrosshair?: boolean;
+	showDatumGlyph?: boolean;
+	showSeriesGlyphs?: boolean;
+	verticalCrosshairStyle?: SVGProps< SVGLineElement >;
+	horizontalCrosshairStyle?: SVGProps< SVGLineElement >;
+	glyphStyle?: SVGProps< SVGCircleElement >;
+	resizeObserverPolyfill?: UseTooltipPortalOptions[ 'polyfill' ];
+} & Omit< VisxTooltipProps, 'left' | 'top' | 'children' > &
+	Pick< UseTooltipPortalOptions, 'debounce' | 'detectBounds' | 'scroll' | 'zIndex' >;
+
 export type { LineStyles, GridStyles } from '@visx/xychart';