@automattic/charts 0.1.0

package/src/components/pie-semi-circle-chart/pie-semi-circle-chart.tsx

@@ -0,0 +1,187 @@
+import { localPoint } from '@visx/event';
+import { Group } from '@visx/group';
+import Pie, { PieArcDatum } from '@visx/shape/lib/shapes/Pie';
+import { Text } from '@visx/text';
+import { useTooltip } from '@visx/tooltip';
+import clsx from 'clsx';
+import { FC, useCallback } from 'react';
+import { useChartTheme } from '../../providers/theme/theme-provider';
+import { Legend } from '../legend';
+import { BaseTooltip } from '../tooltip';
+import styles from './pie-semi-circle-chart.module.scss';
+import type { BaseChartProps, DataPointPercentage } from '../shared/types';
+
+interface PieSemiCircleChartProps extends BaseChartProps< DataPointPercentage[] > {
+	/**
+	 * Label text to display above the chart
+	 */
+	label: string;
+	/**
+	 * Note text to display below the label
+	 */
+	note: string;
+	/**
+	 * Direction of chart rendering
+	 * true for clockwise, false for counter-clockwise
+	 */
+	clockwise?: boolean;
+	/**
+	 * Thickness of the pie chart. A value between 0 and 1
+	 */
+	thickness?: number;
+}
+
+type ArcData = PieArcDatum< DataPointPercentage >;
+
+const PieSemiCircleChart: FC< PieSemiCircleChartProps > = ( {
+	data,
+	width,
+	label,
+	note,
+	className,
+	withTooltips = false,
+	clockwise = true,
+	thickness = 0.4,
+	showLegend,
+	legendOrientation,
+} ) => {
+	const providerTheme = useChartTheme();
+	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
+		useTooltip< DataPointPercentage >();
+
+	const centerX = width / 2;
+	const height = width / 2;
+	const radius = width / 2;
+	const pad = 0.03;
+	const innerRadius = radius * ( 1 - thickness + pad );
+
+	// Map the data to include index for color assignment
+	const dataWithIndex = data.map( ( d, index ) => ( {
+		...d,
+		index,
+	} ) );
+
+	// Set the clockwise direction based on the prop
+	const startAngle = clockwise ? -Math.PI / 2 : Math.PI / 2;
+	const endAngle = clockwise ? Math.PI / 2 : -Math.PI / 2;
+
+	const accessors = {
+		value: ( d: DataPointPercentage & { index: number } ) => d.value,
+		sort: (
+			a: DataPointPercentage & { index: number },
+			b: DataPointPercentage & { index: number }
+		) => b.value - a.value,
+		// Use the color property from the data object as a last resort. The theme provides colours by default.
+		fill: ( d: DataPointPercentage & { index: number } ) =>
+			d.color || providerTheme.colors[ d.index % providerTheme.colors.length ],
+	};
+
+	const handleMouseMove = useCallback(
+		( event: React.MouseEvent, arc: ArcData ) => {
+			const coords = localPoint( event );
+			if ( ! coords ) return;
+
+			showTooltip( {
+				tooltipData: arc.data,
+				tooltipLeft: coords.x,
+				tooltipTop: coords.y - 10,
+			} );
+		},
+		[ showTooltip ]
+	);
+
+	const handleMouseLeave = useCallback( () => {
+		hideTooltip();
+	}, [ hideTooltip ] );
+
+	const handleArcMouseMove = useCallback(
+		( arc: ArcData ) => ( event: React.MouseEvent ) => {
+			handleMouseMove( event, arc );
+		},
+		[ handleMouseMove ]
+	);
+
+	// Create legend items
+	const legendItems = data.map( ( item, index ) => ( {
+		label: item.label,
+		value: item.valueDisplay || item.value.toString(),
+		color: accessors.fill( { ...item, index } ),
+	} ) );
+
+	return (
+		<div
+			className={ clsx( 'pie-semi-circle-chart', styles[ 'pie-semi-circle-chart' ], className ) }
+		>
+			<svg width={ width } height={ height }>
+				{ /* Main chart group that contains both the pie and text elements */ }
+				<Group top={ centerX } left={ centerX }>
+					{ /* Pie chart */ }
+					<Pie< DataPointPercentage & { index: number } >
+						data={ dataWithIndex }
+						pieValue={ accessors.value }
+						outerRadius={ radius }
+						innerRadius={ innerRadius }
+						cornerRadius={ 3 }
+						padAngle={ pad }
+						startAngle={ startAngle }
+						endAngle={ endAngle }
+						pieSort={ accessors.sort }
+					>
+						{ pie => {
+							return pie.arcs.map( arc => (
+								<g
+									key={ arc.data.label }
+									onMouseMove={ handleArcMouseMove( arc ) }
+									onMouseLeave={ handleMouseLeave }
+								>
+									<path d={ pie.path( arc ) || '' } fill={ accessors.fill( arc.data ) } />
+								</g>
+							) );
+						} }
+					</Pie>
+
+					<Group>
+						<Text
+							textAnchor="middle"
+							verticalAnchor="start"
+							y={ -40 } // double font size to make room for a note
+							className={ styles.label }
+						>
+							{ label }
+						</Text>
+						<Text
+							textAnchor="middle"
+							verticalAnchor="start"
+							y={ -20 } // font size with padding
+							className={ styles.note }
+						>
+							{ note }
+						</Text>
+					</Group>
+				</Group>
+			</svg>
+
+			{ withTooltips && tooltipOpen && tooltipData && (
+				<BaseTooltip
+					data={ {
+						label: tooltipData.label,
+						value: tooltipData.value,
+						valueDisplay: tooltipData.valueDisplay,
+					} }
+					top={ tooltipTop }
+					left={ tooltipLeft }
+				/>
+			) }
+
+			{ showLegend && (
+				<Legend
+					items={ legendItems }
+					orientation={ legendOrientation }
+					className={ styles[ 'pie-semi-circle-chart-legend' ] }
+				/>
+			) }
+		</div>
+	);
+};
+
+export default PieSemiCircleChart;

package/src/components/shared/types.d.ts

@@ -0,0 +1,109 @@
+import type { CSSProperties } from 'react';
+
+export type DataPoint = {
+	label: string;
+	value: number;
+};
+
+export type DataPointDate = {
+	date: Date;
+	label?: string;
+	value: number;
+};
+
+export type SeriesData = {
+	group?: string;
+	label: string;
+	data: DataPointDate[] | DataPoint[];
+};
+
+export type MultipleDataPointsDate = {
+	label: string;
+	data: DataPointDate[];
+};
+
+export type DataPointPercentage = {
+	/**
+	 * Label for the data point
+	 */
+	label: string;
+	/**
+	 * Numerical value
+	 */
+	value: number;
+	/**
+	 * Formatted value for display
+	 */
+	valueDisplay?: string;
+	/**
+	 * Percentage value
+	 */
+	percentage: number;
+	/**
+	 * Color code for the segment, by default colours are taken from the theme but this property can overrides it
+	 */
+	color?: string;
+};
+
+/**
+ * Theme configuration for chart components
+ */
+export type ChartTheme = {
+	/** Background color for chart components */
+	backgroundColor: string;
+	/** Background color for labels */
+	labelBackgroundColor?: string;
+	/** Array of colors used for data visualization */
+	colors: string[];
+	/** Optional CSS styles for grid lines */
+	gridStyles?: CSSProperties;
+	/** Length of axis ticks in pixels */
+	tickLength: number;
+	/** Color of the grid lines */
+	gridColor: string;
+	/** Color of the grid lines in dark mode */
+	gridColorDark: string;
+};
+
+/**
+ * Base properties shared across all chart components
+ */
+export type BaseChartProps< T = DataPoint | DataPointDate > = {
+	/**
+	 * Array of data points to display in the chart
+	 */
+	data: T extends DataPoint | DataPointDate ? T[] : T;
+	/**
+	 * Additional CSS class name for the chart container
+	 */
+	className?: string;
+	/**
+	 * Width of the chart in pixels
+	 */
+	width: number;
+	/**
+	 * Height of the chart in pixels
+	 */
+	height?: number;
+	/**
+	 * Chart margins
+	 */
+	margin?: {
+		top: number;
+		right: number;
+		bottom: number;
+		left: number;
+	};
+	/**
+	 * Whether to show tooltips on hover. False by default.
+	 */
+	withTooltips?: boolean;
+	/**
+	 * Whether to show legend
+	 */
+	showLegend?: boolean;
+	/**
+	 * Legend orientation
+	 */
+	legendOrientation?: 'horizontal' | 'vertical';
+};

package/src/components/tooltip/base-tooltip.module.scss

@@ -0,0 +1,11 @@
+.tooltip {
+  padding: 0.5rem;
+  background-color: rgba(0, 0, 0, 0.85);
+  color: white;
+  border-radius: 4px;
+  font-size: 14px;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+  position: absolute;
+  pointer-events: none;
+  transform: translate(-50%, -100%);
+}

package/src/components/tooltip/base-tooltip.tsx

@@ -0,0 +1,57 @@
+import styles from './base-tooltip.module.scss';
+import type { CSSProperties, ComponentType, ReactNode } from 'react';
+
+type TooltipData = {
+	label: string;
+	value: number;
+	valueDisplay?: string;
+};
+
+type TooltipComponentProps = {
+	data: TooltipData;
+	className?: string;
+};
+
+type TooltipCommonProps = {
+	top: number;
+	left: number;
+	style?: CSSProperties;
+	className?: string;
+};
+
+type DefaultDataTooltip = {
+	data: TooltipData;
+	component?: ComponentType< TooltipComponentProps >;
+	children?: never;
+};
+
+type CustomTooltip = {
+	children: ReactNode;
+	data?: never;
+	component?: never;
+};
+
+type BaseTooltipProps = TooltipCommonProps & ( DefaultDataTooltip | CustomTooltip );
+
+const DefaultTooltipContent = ( { data }: TooltipComponentProps ) => (
+	<>
+		{ data?.label }: { data?.valueDisplay || data?.value }
+	</>
+);
+
+export const BaseTooltip = ( {
+	data,
+	top,
+	left,
+	component: Component = DefaultTooltipContent,
+	children,
+	className,
+}: BaseTooltipProps ) => {
+	return (
+		<div className={ styles.tooltip } style={ { top, left } } role="tooltip">
+			{ children || <Component data={ data } className={ className } /> }
+		</div>
+	);
+};
+
+export type { BaseTooltipProps, TooltipData };

package/src/components/tooltip/index.ts

@@ -0,0 +1,2 @@
+export { BaseTooltip } from './base-tooltip';
+export type { BaseTooltipProps, TooltipData } from './base-tooltip';

package/src/components/tooltip/types.ts

@@ -0,0 +1,8 @@
+type TooltipProps = {
+	data: {
+		label: string;
+		value: number;
+	};
+};
+
+export type { TooltipProps };

package/src/hooks/use-chart-mouse-handler.ts

@@ -0,0 +1,90 @@
+import { localPoint } from '@visx/event';
+import { useTooltip } from '@visx/tooltip';
+import { useCallback, type MouseEvent } from 'react';
+import type { DataPoint } from '../components/shared/types';
+
+type UseChartMouseHandlerProps = {
+	/**
+	 * Whether tooltips are enabled
+	 */
+	withTooltips: boolean;
+};
+
+type UseChartMouseHandlerReturn = {
+	/**
+	 * Handler for mouse move events
+	 */
+	onMouseMove: ( event: React.MouseEvent< SVGElement >, data: DataPoint ) => void;
+	/**
+	 * Handler for mouse leave events
+	 */
+	onMouseLeave: () => void;
+	/**
+	 * Whether the tooltip is currently open
+	 */
+	tooltipOpen: boolean;
+	/**
+	 * The current tooltip data
+	 */
+	tooltipData: DataPoint | null;
+	/**
+	 * The current tooltip left position
+	 */
+	tooltipLeft: number | undefined;
+	/**
+	 * The current tooltip top position
+	 */
+	tooltipTop: number | undefined;
+};
+
+/**
+ * Hook to handle mouse interactions for chart components
+ *
+ * @param {UseChartMouseHandlerProps} props - Hook configuration
+ * @return {UseChartMouseHandlerReturn} Object containing handlers and tooltip state
+ */
+const useChartMouseHandler = ( {
+	withTooltips,
+}: UseChartMouseHandlerProps ): UseChartMouseHandlerReturn => {
+	const { tooltipOpen, tooltipLeft, tooltipTop, tooltipData, hideTooltip, showTooltip } =
+		useTooltip< DataPoint >();
+
+	// TODO: either debounce/throttle or use useTooltipInPortal with built-in debounce
+	const onMouseMove = useCallback(
+		( event: MouseEvent< SVGElement >, data: DataPoint ) => {
+			if ( ! withTooltips ) {
+				return;
+			}
+
+			const coords = localPoint( event );
+			if ( ! coords ) {
+				return;
+			}
+
+			showTooltip( {
+				tooltipData: data,
+				tooltipLeft: coords.x,
+				tooltipTop: coords.y - 10,
+			} );
+		},
+		[ withTooltips, showTooltip ]
+	);
+
+	const onMouseLeave = useCallback( () => {
+		if ( ! withTooltips ) {
+			return;
+		}
+		hideTooltip();
+	}, [ withTooltips, hideTooltip ] );
+
+	return {
+		onMouseMove,
+		onMouseLeave,
+		tooltipOpen,
+		tooltipData,
+		tooltipLeft,
+		tooltipTop,
+	};
+};
+
+export default useChartMouseHandler;

package/src/index.ts

@@ -0,0 +1,19 @@
+// Charts
+export { BarChart } from './components/bar-chart';
+export { LineChart } from './components/line-chart';
+export { PieChart } from './components/pie-chart';
+export { PieSemiCircleChart } from './components/pie-semi-circle-chart';
+
+// Chart components
+export { BaseTooltip } from './components/tooltip';
+export { Legend } from './components/legend';
+
+// Providers
+export { ThemeProvider } from './providers/theme';
+
+// Hooks
+export { default as useChartMouseHandler } from './hooks/use-chart-mouse-handler';
+
+// Types
+export type * from './components/shared/types';
+export type { BaseTooltipProps } from './components/tooltip';

package/src/providers/theme/index.ts

@@ -0,0 +1,2 @@
+export { ThemeProvider, useChartTheme } from './theme-provider';
+export { defaultTheme, jetpackTheme, wooTheme } from './themes';

package/src/providers/theme/theme-provider.tsx

@@ -0,0 +1,36 @@
+import { createContext, useContext, FC, ReactNode } from 'react';
+import { defaultTheme } from './themes';
+import type { ChartTheme } from '../../components/shared/types';
+
+/**
+ * Context for sharing theme configuration across components
+ */
+const ThemeContext = createContext< ChartTheme >( defaultTheme );
+
+/**
+ * Hook to access chart theme
+ * @return {object} A built theme configuration compatible with visx charts
+ */
+const useChartTheme = () => {
+	const theme = useContext( ThemeContext );
+	return theme;
+};
+
+/**
+ * Props for the ThemeProvider component
+ */
+type ThemeProviderProps = {
+	/** Optional partial theme override */
+	theme?: Partial< ChartTheme >;
+	/** Child components that will have access to the theme */
+	children: ReactNode;
+};
+
+// Provider component for chart theming
+// Allows theme customization through props while maintaining default values
+const ThemeProvider: FC< ThemeProviderProps > = ( { theme = {}, children } ) => {
+	const mergedTheme = { ...defaultTheme, ...theme };
+	return <ThemeContext.Provider value={ mergedTheme }>{ children }</ThemeContext.Provider>;
+};
+
+export { ThemeProvider, useChartTheme };

package/src/providers/theme/themes.ts

@@ -0,0 +1,51 @@
+import type { ChartTheme } from '../../components/shared/types';
+
+/**
+ * Default theme configuration
+ */
+const defaultTheme: ChartTheme = {
+	backgroundColor: '#FFFFFF', // chart background color
+	labelBackgroundColor: '#FFFFFF', // label background color
+	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
+	gridStyles: {
+		stroke: '#787C82',
+		strokeWidth: 1,
+	},
+	tickLength: 0,
+	gridColor: '',
+	gridColorDark: '',
+};
+
+/**
+ * Jetpack theme configuration
+ */
+const jetpackTheme: ChartTheme = {
+	backgroundColor: '#FFFFFF', // chart background color
+	labelBackgroundColor: '#FFFFFF', // label background color
+	colors: [ '#98C8DF', '#006DAB', '#A6DC80', '#1F9828', '#FF8C8F' ],
+	gridStyles: {
+		stroke: '#787C82',
+		strokeWidth: 1,
+	},
+	tickLength: 0,
+	gridColor: '',
+	gridColorDark: '',
+};
+
+/**
+ * Woo theme configuration
+ */
+const wooTheme: ChartTheme = {
+	backgroundColor: '#FFFFFF', // chart background color
+	labelBackgroundColor: '#FFFFFF', // label background color
+	colors: [ '#80C8FF', '#B999FF', '#3858E9' ],
+	gridStyles: {
+		stroke: '#787C82',
+		strokeWidth: 1,
+	},
+	tickLength: 0,
+	gridColor: '',
+	gridColorDark: '',
+};
+
+export { defaultTheme, jetpackTheme, wooTheme };

package/tests/index.test.js

@@ -0,0 +1,18 @@
+// We recommend using `jest` for testing. If you're testing React code, we recommend `@testing-library/react` and related packages.
+// Please match the versions used elsewhere in the monorepo.
+//
+// Please don't add new uses of `mocha`, `chai`, `sinon`, `enzyme`, and so on. We're trying to standardize on one testing framework.
+//
+// The default setup is to have files named like "name.test.js" (or .jsx, .ts, or .tsx) in this `tests/` directory.
+// But you could instead put them in `src/`, or put files like "name.js" (or .jsx, .ts, or .tsx) in `test` or `__tests__` directories somewhere.
+
+// This is a placeholder test, new tests will be added soon
+const placeholderFunction = () => {
+	return true;
+};
+
+describe( 'placeholderTest', () => {
+	it( 'should be a function', () => {
+		expect( typeof placeholderFunction ).toBe( 'function' );
+	} );
+} );

package/tests/jest.config.cjs

@@ -0,0 +1,7 @@
+const path = require( 'path' );
+const baseConfig = require( 'jetpack-js-tools/jest/config.base.js' );
+
+module.exports = {
+	...baseConfig,
+	rootDir: path.join( __dirname, '..' ),
+};