@automattic/charts 0.16.2 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "0.16.2",
+	"version": "0.18.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -47,7 +47,8 @@
 		"./style.css": "./dist/mjs/style.css"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.0.8",
+		"@automattic/jetpack-components": "^1.1.14",
+		"@automattic/number-formatters": "^1.0.9",
 		"@babel/runtime": "7.27.6",
 		"@react-spring/web": "9.7.5",
 		"@visx/annotation": "^3.12.0",
@@ -67,15 +68,15 @@
 		"@visx/xychart": "^3.12.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
-		"lodash": "^4.17.21",
+		"deepmerge": "4.3.1",
 		"tslib": "2.5.0"
 	},
 	"devDependencies": {
 		"@automattic/jetpack-webpack-config": "workspace:*",
-		"@babel/core": "7.27.7",
+		"@babel/core": "7.28.0",
 		"@babel/plugin-transform-react-jsx": "7.27.1",
-		"@babel/plugin-transform-runtime": "7.27.4",
-		"@babel/preset-env": "7.27.2",
+		"@babel/plugin-transform-runtime": "7.28.0",
+		"@babel/preset-env": "7.28.0",
 		"@babel/preset-react": "7.27.1",
 		"@babel/preset-typescript": "7.27.1",
 		"@rollup/plugin-commonjs": "26.0.1",
@@ -83,8 +84,8 @@
 		"@rollup/plugin-node-resolve": "15.3.0",
 		"@rollup/plugin-terser": "0.4.3",
 		"@rollup/plugin-typescript": "12.1.0",
-		"@storybook/blocks": "8.6.7",
-		"@storybook/react": "8.6.7",
+		"@storybook/addon-docs": "9.0.15",
+		"@storybook/react": "9.0.15",
 		"@testing-library/dom": "^10.0.0",
 		"@testing-library/jest-dom": "^6.0.0",
 		"@testing-library/react": "^16.0.0",
@@ -93,6 +94,7 @@
 		"@types/react": "18.3.23",
 		"@types/react-dom": "18.3.7",
 		"@visx/glyph": "3.12.0",
+		"@wordpress/components": "29.12.0",
 		"@wordpress/element": "6.26.0",
 		"babel-jest": "30.0.0",
 		"babel-loader": "9.1.2",
@@ -114,7 +116,7 @@
 		"sass": "npm:sass-embedded@1.87.0",
 		"sass-embedded": "1.87.0",
 		"sass-loader": "^16.0.0",
-		"storybook": "8.6.7",
+		"storybook": "9.0.15",
 		"tsconfig-paths-webpack-plugin": "4.2.0",
 		"typescript": "5.8.3",
 		"webpack": "^5.88.0",

package/src/components/bar-chart/bar-chart.tsx

@@ -1,13 +1,15 @@
 import { PatternLines, PatternCircles, PatternWaves, PatternHexagons } from '@visx/pattern';
-import { Axis, BarSeries, BarGroup, Grid, Tooltip, XYChart } from '@visx/xychart';
+import { Axis, BarSeries, BarGroup, Grid, XYChart } from '@visx/xychart';
 import clsx from 'clsx';
-import { useCallback, useId } from 'react';
-import { useXYChartTheme } from '../../providers/theme';
+import { useCallback, useId, useState, useRef, useMemo } from 'react';
+import { ChartProvider, useChartId, useChartRegistration } from '../../providers/chart-context';
+import { useChartTheme, useXYChartTheme } from '../../providers/theme';
 import { Legend } from '../legend';
 import { useChartDataTransform } from '../shared/use-chart-data-transform';
 import { useChartMargin } from '../shared/use-chart-margin';
 import { useElementHeight } from '../shared/use-element-height';
 import { withResponsive } from '../shared/with-responsive';
+import { AccessibleTooltip, useKeyboardNavigation } from '../tooltip/accessible-tooltip';
 import styles from './bar-chart.module.scss';
 import { useBarChartOptions } from './use-bar-chart-options';
 import type { BaseChartProps, DataPointDate, SeriesData } from '../../types';
@@ -41,8 +43,9 @@ const validateData = ( data: SeriesData[] ) => {
 
 const getPatternId = ( chartId: string, index: number ) => `bar-pattern-${ chartId }-${ index }`;
 
-const BarChart: FC< BarChartProps > = ( {
+const BarChartInternal: FC< BarChartProps > = ( {
 	data,
+	chartId: providedChartId,
 	width,
 	height = 400,
 	className,
@@ -61,7 +64,8 @@ const BarChart: FC< BarChartProps > = ( {
 } ) => {
 	const horizontal = orientation === 'horizontal';
 	// Generate a unique chart ID to avoid pattern conflicts with multiple charts
-	const chartId = useId();
+	const internalChartId = useId();
+	const chartId = useChartId( providedChartId );
 	const theme = useXYChartTheme( data );
 
 	const dataSorted = useChartDataTransform( data );
@@ -69,6 +73,22 @@ const BarChart: FC< BarChartProps > = ( {
 	const chartOptions = useBarChartOptions( dataSorted, horizontal, options );
 	const defaultMargin = useChartMargin( height, chartOptions, dataSorted, theme, horizontal );
 	const [ legendRef, legendHeight ] = useElementHeight< HTMLDivElement >();
+	const chartRef = useRef< HTMLDivElement >( null );
+	const [ selectedIndex, setSelectedIndex ] = useState< number | undefined >( undefined );
+	const [ isNavigating, setIsNavigating ] = useState( false );
+
+	const totalPoints =
+		Math.max( 0, ...data.map( series => series.data?.length || 0 ) ) * data.length;
+
+	// Use the keyboard navigation hook
+	const { tooltipRef, onChartFocus, onChartBlur, onChartKeyDown } = useKeyboardNavigation( {
+		selectedIndex,
+		setSelectedIndex,
+		isNavigating,
+		setIsNavigating,
+		chartRef,
+		totalPoints,
+	} );
 
 	const getColor = useCallback(
 		( seriesData: SeriesData, index: number ) =>
@@ -79,9 +99,9 @@ const BarChart: FC< BarChartProps > = ( {
 	const getBarBackground = useCallback(
 		( index: number ) => () =>
 			withPatterns
-				? `url(#${ getPatternId( chartId, index ) })`
+				? `url(#${ getPatternId( internalChartId, index ) })`
 				: getColor( dataSorted[ index ], index ),
-		[ withPatterns, getColor, dataSorted, chartId ]
+		[ withPatterns, getColor, dataSorted, internalChartId ]
 	);
 
 	const renderDefaultTooltip = useCallback(
@@ -114,7 +134,7 @@ const BarChart: FC< BarChartProps > = ( {
 	const renderPattern = useCallback(
 		( index: number, color: string ) => {
 			const patternType = index % 4;
-			const id = getPatternId( chartId, index );
+			const id = getPatternId( internalChartId, index );
 			const commonProps = {
 				id,
 				stroke: 'white',
@@ -144,12 +164,12 @@ const BarChart: FC< BarChartProps > = ( {
 					return <PatternHexagons key={ id } { ...commonProps } size={ 8 } height={ 3 } />;
 			}
 		},
-		[ chartId ]
+		[ internalChartId ]
 	);
 
 	const createPatternBorderStyle = useCallback(
 		( index: number, color: string ) => {
-			const patternId = getPatternId( chartId, index );
+			const patternId = getPatternId( internalChartId, index );
 			return `
 			.visx-bar[fill="url(#${ patternId })"] {
 				stroke: ${ color };
@@ -157,30 +177,82 @@ const BarChart: FC< BarChartProps > = ( {
 				}
 			`;
 		},
-		[ chartId ]
+		[ internalChartId ]
 	);
 
-	// Validate data using the same pattern as LineChart
+	const createKeyboardHighlightStyle = useCallback( () => {
+		if ( selectedIndex === undefined ) return '';
+
+		// Calculate which bar should be highlighted based on selectedIndex
+		// Pattern: [series1[0], series2[0], series3[0], series1[1], series2[1], series3[1], ...]
+		const maxDataPoints = Math.max( ...data.map( s => s.data.length ) );
+		const dataPointIndex = Math.floor( selectedIndex / data.length );
+		const seriesIndex = selectedIndex % data.length;
+
+		// Only highlight if we're within valid bounds
+		if ( dataPointIndex >= maxDataPoints || seriesIndex >= data.length ) {
+			return '';
+		}
+
+		const seriesData = data[ seriesIndex ];
+		if ( dataPointIndex >= seriesData.data.length ) {
+			return '';
+		}
+
+		// Based on the DOM structure analysis:
+		// - All bars are in a single .visx-bar-group
+		// - Bars are ordered as: [series1[0], series1[1], series2[0], series2[1], ...]
+		// - So we need to calculate the actual bar index in the DOM
+		const actualBarIndex = seriesIndex * maxDataPoints + dataPointIndex;
+
+		// Use a CSS class selector instead of ID since useId() generates invalid CSS ID characters
+		const generatedStyles = `
+			.bar-chart[data-chart-id="bar-chart-${ chartId }"] .visx-bar-group .visx-bar:nth-child(${
+				actualBarIndex + 1
+			}) {
+				stroke: #005fcc;
+				stroke-width: 2px;
+			}
+		`;
+
+		return generatedStyles;
+	}, [ selectedIndex, data, chartId ] );
+
+	// Validate data first
 	const error = validateData( dataSorted );
+	const isDataValid = ! error;
+
+	// Create legend items (hooks must be called in same order every render)
+	const legendItems = useMemo(
+		() =>
+			dataSorted.map( ( group, index ) => ( {
+				label: group.label, // Label for each unique group
+				value: '', // Empty string since we don't want to show a specific value
+				color: getColor( group, index ),
+				shapeStyle: group?.options?.legendShapeStyle,
+			} ) ),
+		[ dataSorted, getColor ]
+	);
+
+	// Register chart with context only if data is valid
+	const providerTheme = useChartTheme();
+	useChartRegistration( chartId, legendItems, providerTheme, 'bar', isDataValid, {
+		orientation,
+		withPatterns,
+	} );
+
 	if ( error ) {
 		return <div className={ clsx( 'bar-chart', styles[ 'bar-chart' ] ) }>{ error }</div>;
 	}
 
-	// Create legend items from group labels, this iterates over groups rather than data points
-	const legendItems = dataSorted.map( ( group, index ) => ( {
-		label: group.label, // Label for each unique group
-		value: '', // Empty string since we don't want to show a specific value
-		color: getColor( group, index ),
-		shapeStyle: group?.options?.legendShapeStyle,
-	} ) );
-
 	const gridVisibility = gridVisibilityProp ?? chartOptions.gridVisibility;
+	const highlightedBarStyle = createKeyboardHighlightStyle();
 
 	return (
 		<div
 			className={ clsx( 'bar-chart', styles[ 'bar-chart' ], className ) }
 			data-testid="bar-chart"
-			role="img"
+			role="grid"
 			aria-label="bar chart"
 			style={ {
 				width,
@@ -189,6 +261,12 @@ const BarChart: FC< BarChartProps > = ( {
 				flexDirection:
 					showLegend && legendAlignmentVertical === 'top' ? 'column-reverse' : 'column',
 			} }
+			tabIndex={ 0 }
+			onKeyDown={ onChartKeyDown }
+			onFocus={ onChartFocus }
+			onBlur={ onChartBlur }
+			ref={ chartRef }
+			data-chart-id={ `bar-chart-${ chartId }` } // Unique ID for the chart
 		>
 			<XYChart
 				theme={ theme }
@@ -227,6 +305,8 @@ const BarChart: FC< BarChartProps > = ( {
 					</>
 				) }
 
+				{ highlightedBarStyle && <style>{ highlightedBarStyle }</style> }
+
 				<BarGroup padding={ chartOptions.barGroup.padding }>
 					{ dataSorted.map( ( seriesData, index ) => (
 						<BarSeries
@@ -244,11 +324,16 @@ const BarChart: FC< BarChartProps > = ( {
 				<Axis { ...chartOptions.axis.y } />
 
 				{ withTooltips && (
-					<Tooltip
+					<AccessibleTooltip
 						detectBounds
 						snapTooltipToDatumX
 						snapTooltipToDatumY
 						renderTooltip={ renderTooltip || renderDefaultTooltip }
+						selectedIndex={ selectedIndex }
+						tooltipRef={ tooltipRef }
+						keyboardFocusedClassName={ styles[ 'bar-chart__tooltip--keyboard-focused' ] }
+						series={ data }
+						mode="individual"
 					/>
 				) }
 			</XYChart>
@@ -268,4 +353,12 @@ const BarChart: FC< BarChartProps > = ( {
 	);
 };
 
+const BarChart: FC< BarChartProps > = props => (
+	<ChartProvider>
+		<BarChartInternal { ...props } />
+	</ChartProvider>
+);
+
+BarChart.displayName = 'BarChart';
+
 export default withResponsive< BarChartProps >( BarChart );

package/src/components/grid-control/grid-control.module.scss

@@ -3,9 +3,9 @@ $grid-line-color: #d7d6d6;
 
 .grid-control {
 
-  :global(.visx-line) {
-    stroke: $grid-line-color;
-    stroke-width: 1px;
-    shape-rendering: crispEdges;
-  }
-} 
+	:global(.visx-line) {
+		stroke: $grid-line-color;
+		stroke-width: 1px;
+		shape-rendering: crispEdges;
+	}
+}

package/src/components/leaderboard-chart/README.md

@@ -0,0 +1,199 @@
+# LeaderboardChart Component
+
+A flexible and accessible leaderboard chart component for displaying ranked data with WordPress ProgressBar components and optional comparison values.
+
+## Features
+
+- 📊 Clean, responsive leaderboard visualization
+- 🎨 Customizable colors and styling
+- 🔄 Optional comparison data support
+- 📱 Mobile-friendly design
+- 🎯 TypeScript support with full type definitions
+- ♿ Accessible design
+- 🧪 Comprehensive test coverage
+- 📖 Storybook documentation
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { LeaderboardChart } from '@automattic/charts';
+
+const data = [
+  {
+    id: 'direct',
+    label: 'Direct',
+    currentValue: 12500,
+    previousValue: 10000,
+    currentShare: 100,
+    previousShare: 80,
+    delta: 25,
+  },
+  // ... more entries
+];
+
+function MyComponent() {
+  return (
+    <LeaderboardChart
+      data={data}
+      withComparison={true}
+      primaryColor="#3858E9"
+      secondaryColor="#66BDFF"
+    />
+  );
+}
+```
+
+### With Custom Formatters
+
+```typescript
+import { LeaderboardChart } from '@automattic/charts';
+
+function CustomFormattedChart() {
+  return (
+    <LeaderboardChart
+      data={data}
+      withComparison={true}
+      valueFormatter={(value) => `$${(value / 1000).toFixed(1)}k`}
+      deltaFormatter={(value) => `${value > 0 ? '+' : ''}${value}%`}
+    />
+  );
+}
+```
+
+### Preparing Your Data
+
+The LeaderboardChart expects pre-processed data. You'll need to transform your raw data into the required format:
+
+```typescript
+import { LeaderboardChart } from '@automattic/charts';
+
+// Transform your raw data into LeaderboardEntry format
+function transformRawData(rawData) {
+  const maxValue = Math.max(...rawData.map(item => item.current_period.value));
+  
+  return rawData.map(item => ({
+    id: item.id,
+    label: item.name,
+    currentValue: item.current_period.value,
+    previousValue: item.previous_period.value,
+    currentShare: (item.current_period.value / maxValue) * 100,
+    previousShare: (item.previous_period.value / maxValue) * 100,
+    delta: ((item.current_period.value - item.previous_period.value) / item.previous_period.value) * 100,
+  }));
+}
+
+function ProcessedDataChart() {
+  const processedData = transformRawData(rawData);
+  
+  return (
+    <LeaderboardChart
+      data={processedData}
+      withComparison={true}
+    />
+  );
+}
+```
+
+## API Reference
+
+### LeaderboardChart Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `LeaderboardEntry[]` | **required** | Array of leaderboard entries to display |
+| `withComparison` | `boolean` | `false` | Whether to show comparison data |
+| `loading` | `boolean` | `false` | Whether the chart is in loading state |
+| `primaryColor` | `string` | `#3858E9` | Primary color for current period bars |
+| `secondaryColor` | `string` | `#66BDFF` | Secondary color for comparison period bars |
+| `valueFormatter` | `(value: number) => string` | *compact formatter* | Custom formatter for values |
+| `deltaFormatter` | `(value: number) => string` | *percentage formatter* | Custom formatter for delta values |
+| `className` | `string` | `undefined` | Additional CSS class name |
+| `style` | `React.CSSProperties` | `undefined` | Custom styling for the chart container |
+
+### LeaderboardEntry Interface
+
+```typescript
+interface LeaderboardEntry {
+  id: string;              // Unique identifier
+  label: string;           // Display name
+  currentValue: number;    // Current period value
+  previousValue: number;   // Previous period value
+  currentShare: number;    // Current bar width (0-100)
+  previousShare: number;   // Previous bar width (0-100)
+  delta: number;           // Percentage change
+}
+```
+
+## Data Transformation
+
+Since the LeaderboardChart expects pre-processed data, you'll need to handle data transformation in your application. This gives you full control over how your specific data structures are converted and allows for custom business logic.
+
+## Styling
+
+The component uses CSS Modules for styling. You can customize colors using CSS custom properties:
+
+```css
+.myCustomChart {
+  --primary-color: #ff6b6b;
+  --secondary-color: #4ecdc4;
+}
+```
+
+## Accessibility
+
+The component includes:
+- Semantic HTML structure
+- Proper color contrast ratios
+- Keyboard navigation support
+- Screen reader compatible markup
+
+## Examples
+
+### E-commerce Sales Channels
+
+```typescript
+const salesData = [
+  { id: 'organic', label: 'Organic Search', currentValue: 45000, previousValue: 38000, currentShare: 100, previousShare: 84, delta: 18 },
+  { id: 'paid', label: 'Paid Advertising', currentValue: 32000, previousValue: 35000, currentShare: 71, previousShare: 78, delta: -9 },
+  { id: 'social', label: 'Social Media', currentValue: 18000, previousValue: 15000, currentShare: 40, previousShare: 33, delta: 20 },
+  { id: 'email', label: 'Email Marketing', currentValue: 12000, previousValue: 11000, currentShare: 27, previousShare: 24, delta: 9 },
+];
+
+<LeaderboardChart data={salesData} withComparison={true} />
+```
+
+### Traffic Sources
+
+```typescript
+const trafficData = [
+  { id: 'direct', label: 'Direct', currentValue: 15420, previousValue: 13200, currentShare: 100, previousShare: 86, delta: 17 },
+  { id: 'search', label: 'Search Engines', currentValue: 12350, previousValue: 11800, currentShare: 80, previousShare: 77, delta: 5 },
+  { id: 'social', label: 'Social Networks', currentValue: 8760, previousValue: 9200, currentShare: 57, previousShare: 60, delta: -5 },
+];
+
+<LeaderboardChart data={trafficData} withComparison={true} />
+```
+
+## Testing
+
+The component includes comprehensive tests covering:
+- Component rendering
+- Data formatting
+- Comparison functionality
+- Custom formatters
+- Loading states
+- Empty data handling
+
+Run tests with:
+```bash
+pnpm test
+```
+
+## Storybook
+
+Interactive examples and documentation are available in Storybook:
+```bash
+pnpm storybook
+```

package/src/components/leaderboard-chart/index.tsx

@@ -0,0 +1,4 @@
+export { default as LeaderboardChart } from './leaderboard-chart';
+export type { LeaderboardChartProps, LeaderboardEntry } from './leaderboard-chart';
+export { formatMetricValue } from '../shared/format-metric-value';
+export type { MetricValueType } from '../shared/format-metric-value';

package/src/components/leaderboard-chart/leaderboard-chart.module.scss

@@ -0,0 +1,93 @@
+.leaderboardChart {
+	width: 100%;
+	max-width: 400px;
+	display: flex;
+	flex-direction: column;
+	gap: 12px;
+
+	transition: opacity 0.3s ease-in-out;
+
+	&.loading {
+		opacity: 0.5;
+	}
+}
+
+.entryContainer {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr) auto;
+	column-gap: 4px;
+	align-items: start;
+}
+
+.labelContainer {
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+	min-width: 0;
+}
+
+.entryLabel {
+	font-size: 14px;
+	line-height: 1.4;
+	color: #1e1e1e;
+	font-weight: 400;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.progressContainer {
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+
+	.progressBar {
+		width: 100%;
+		height: 6px;
+		border-radius: 2px;
+		background-color: transparent;
+		overflow: hidden;
+		transition: width 0.3s ease-in-out;	
+
+		> div {
+			background-color: var(--progress-color, #3858e9);
+		}
+	}
+
+	.primaryBar {
+		--progress-color: var(--primary-color, #3858e9);
+	}
+	
+	.secondaryBar {
+		--progress-color: var(--secondary-color, #66bdff);
+	}
+}
+
+.valueContainer {
+	display: flex;
+	flex-direction: row;
+	gap: 4px;
+	align-items: flex-start;
+	text-align: right;
+}
+
+.currentValue {
+	font-size: 14px;
+	line-height: 1.4;
+	font-weight: 500;
+	color: #1e1e1e;
+}
+
+.deltaValue {
+	font-size: 13px;
+	line-height: 1.4;
+	font-weight: 400;
+}
+
+.emptyState {
+	padding: 32px 16px;
+	text-align: center;
+	color: #666;
+	font-size: 14px;
+	font-style: italic;
+}