@automattic/charts 0.26.0 → 0.28.0

package/dist/mjs/providers/chart-context/utils.js

@@ -1,20 +1,27 @@
 import { useId, useMemo, useEffect } from 'react';
+import { useDeepMemo } from '../../hooks/use-deep-memo.js';
 import { useGlobalChartsContext } from './global-charts-provider.js';
+import '../theme/theme-provider.js';
+import 'deepmerge';
+import '@visx/event';
+import '@visx/tooltip';
+import '@visx/xychart';
 
 const useChartId = (providedId) => {
     const generatedId = useId();
     return providedId || generatedId;
 };
-const useChartRegistration = (chartId, legendItems, theme, chartType, isDataValid, metadata) => {
+const useChartRegistration = ({ chartId, legendItems, chartType, isDataValid, metadata, }) => {
     const { registerChart, unregisterChart } = useGlobalChartsContext();
+    // Memoize legendItems with deep comparison to prevent infinite loops
+    const stableLegendItems = useDeepMemo(legendItems);
     // Memoize metadata to prevent unnecessary re-renders
     const memoizedMetadata = useMemo(() => metadata, [metadata]);
     useEffect(() => {
         // Only register if data is valid
         if (isDataValid) {
             registerChart(chartId, {
-                legendItems,
-                theme,
+                legendItems: stableLegendItems,
                 chartType,
                 metadata: memoizedMetadata,
             });
@@ -25,8 +32,7 @@ const useChartRegistration = (chartId, legendItems, theme, chartType, isDataVali
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [
         chartId,
-        legendItems,
-        theme,
+        stableLegendItems,
         chartType,
         memoizedMetadata,
         isDataValid,

package/dist/mjs/providers/theme/index.js

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

package/dist/mjs/providers/theme/theme-provider.js

@@ -1,12 +1,10 @@
 import { jsx } from 'react/jsx-runtime';
-import { buildChartTheme } from '@visx/xychart';
-import { createContext, useContext, useMemo } from 'react';
-import { defaultTheme } from './themes.js';
+import { createContext, useContext } from 'react';
 
 /**
  * Context for sharing theme configuration across components
  */
-const ThemeContext = createContext(defaultTheme);
+const ThemeContext = createContext({});
 /**
  * Hook to access chart theme
  * @return {object} A built theme configuration compatible with visx charts
@@ -15,23 +13,10 @@ const useChartTheme = () => {
     const theme = useContext(ThemeContext);
     return theme;
 };
-const useXYChartTheme = (data) => {
-    const providerTheme = useChartTheme();
-    return useMemo(() => {
-        const seriesColors = (data ?? [])
-            .map(series => series.options?.stroke)
-            .filter((color) => Boolean(color));
-        return buildChartTheme({
-            ...providerTheme,
-            colors: [...seriesColors, ...(providerTheme.colors ?? [])],
-        });
-    }, [providerTheme, data]);
-};
 // Provider component for chart theming
 // Allows theme customization through props while maintaining default values
 const ThemeProvider = ({ theme = {}, children }) => {
-    const mergedTheme = { ...defaultTheme, ...theme };
-    return jsx(ThemeContext.Provider, { value: mergedTheme, children: children });
+    return jsx(ThemeContext.Provider, { value: theme, children: children });
 };
 
-export { ThemeProvider, useChartTheme, useXYChartTheme };
+export { ThemeProvider, useChartTheme };

package/dist/mjs/style.css

@@ -1 +1 @@
-.legend-module_legend--horizontal__IUN13{display:flex;flex-direction:row;flex-wrap:wrap;gap:16px}.legend-module_legend--vertical__Scfzo{display:flex;flex-direction:column;gap:8px}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-start__Na2Qp{align-items:flex-start}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-center__FVB2r{align-items:center}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-end__6Vuay{align-items:flex-end}.legend-module_legend--position-top__uh7-2{position:relative}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-start__Na2Qp{justify-content:flex-start}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-center__FVB2r{justify-content:center}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-end__6Vuay{justify-content:flex-end}.legend-module_legend--position-bottom__6Q3j-{position:relative}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-start__Na2Qp{justify-content:flex-start}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-center__FVB2r{justify-content:center}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-end__6Vuay{justify-content:flex-end}.legend-module_legend-item__feemn{align-items:center;display:flex;font-size:.875rem}.legend-module_legend-item-label__ksx6I{align-items:center;display:flex;gap:.5rem}.legend-module_legend-item-value__d9x1j{font-weight:500}.bar-chart-module_bar-chart__lmYNi{display:flex;flex-direction:column}.bar-chart-module_bar-chart__lmYNi svg{overflow:visible}.bar-chart-module_bar-chart-legend__vgKKq{margin-top:1rem}.line-chart-module_line-chart__ITM3d{display:flex;flex-direction:column}.line-chart-module_line-chart__ITM3d svg{overflow:visible}.line-chart-module_line-chart__annotation-label-popover__TqNZk,.line-chart-module_line-chart__tooltip__aqcme{background:#fff;padding:.5rem}.line-chart-module_line-chart__tooltip-date__4Dzab{font-weight:700;padding-bottom:10px}.line-chart-module_line-chart__tooltip-row__6A37G{align-items:center;display:flex;justify-content:space-between;padding:4px 0}.line-chart-module_line-chart__tooltip-label__IvnFF{font-weight:500;padding-right:1rem}.line-chart-module_line-chart__annotations-overlay__4nR2p{left:0;overflow:visible;pointer-events:none;position:absolute;top:0}.line-chart-module_line-chart__annotation-label__OmgiT{pointer-events:auto}.line-chart-module_line-chart__annotation-label-trigger-button__mcIb3{align-items:center;background:none;border:none;cursor:pointer;display:flex;justify-content:center;padding:0;pointer-events:auto}.line-chart-module_line-chart__annotation-label-popover__TqNZk{background:#fff;border:none;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,.1);font-size:14px;margin:.5rem;min-width:125px;position:fixed;visibility:hidden}.line-chart-module_line-chart__annotation-label-popover--visible__dE0cV{visibility:visible}.line-chart-module_line-chart__annotation-label-popover--safari__i3NHT{margin:auto;position:static}.line-chart-module_line-chart__annotation-label-popover-header__Owypo{align-items:start;display:flex;flex-direction:row;justify-content:space-between}.line-chart-module_line-chart__annotation-label-popover-content__vtgQt{padding:.5rem}.line-chart-module_line-chart__annotation-label-popover-close-button__i8KUc{align-items:center;background:none;border:none;cursor:pointer;display:flex;height:44px;justify-content:center;padding:0;width:44px}.visx-tooltip-glyph svg{height:10px;width:10px}.base-tooltip-module_tooltip__OfX6n{background-color:rgba(0,0,0,.85);border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,.1);color:#fff;font-size:14px;padding:.5rem;pointer-events:none;position:absolute;transform:translate(-50%,-100%)}.pie-chart-module_pie-chart__R12Vh{display:flex;flex-direction:column;overflow:hidden}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9{display:flex;flex-direction:column;text-align:center}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9 .pie-semi-circle-chart-module_label__nPqOg{font-size:16px;font-weight:600;margin-bottom:0}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9 .pie-semi-circle-chart-module_note__LpBZQ{font-size:14px;margin-top:0}.leaderboard-chart-module_leaderboardChart__zxakP{transition:opacity .3s ease-in-out}.leaderboard-chart-module_leaderboardChart__zxakP.leaderboard-chart-module_loading__-AGv-{opacity:.5}.leaderboard-chart-module_progressContainer__BZGbj{display:flex;flex-direction:column;gap:6px}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_progressBar__LAQaj{background-color:transparent;border-radius:2px;height:6px;overflow:hidden;transition:width .3s ease-in-out;width:100%}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_progressBar__LAQaj>div{background-color:var(--progress-color,#3858e9)}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_primaryBar__iybII{--progress-color:var(--primary-color,#3858e9)}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_secondaryBar__A7tLz{--progress-color:var(--secondary-color,#66bdff)}.leaderboard-chart-module_valueContainer__ZlLh4{display:flex;gap:4px;justify-content:flex-end}.leaderboard-chart-module_emptyState__0dkfy{color:#666;font-size:14px;font-style:italic;padding:32px 16px;text-align:center}
+.legend-module_legend--horizontal__IUN13{display:flex;flex-direction:row;flex-wrap:wrap;gap:16px}.legend-module_legend--vertical__Scfzo{display:flex;flex-direction:column;gap:8px}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-start__Na2Qp{align-items:flex-start}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-center__FVB2r{align-items:center}.legend-module_legend--vertical__Scfzo.legend-module_legend--alignment-end__6Vuay{align-items:flex-end}.legend-module_legend--position-top__uh7-2{position:relative}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-start__Na2Qp{justify-content:flex-start}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-center__FVB2r{justify-content:center}.legend-module_legend--position-top__uh7-2.legend-module_legend--alignment-end__6Vuay{justify-content:flex-end}.legend-module_legend--position-bottom__6Q3j-{position:relative}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-start__Na2Qp{justify-content:flex-start}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-center__FVB2r{justify-content:center}.legend-module_legend--position-bottom__6Q3j-.legend-module_legend--alignment-end__6Vuay{justify-content:flex-end}.legend-module_legend-item__feemn{align-items:center;display:flex;font-size:.875rem}.legend-module_legend-item-label__ksx6I{align-items:center;display:flex;gap:.5rem}.legend-module_legend-item-value__d9x1j{font-weight:500}.bar-chart-module_bar-chart__lmYNi{display:flex;flex-direction:column}.bar-chart-module_bar-chart__lmYNi svg{overflow:visible}.bar-chart-module_bar-chart-legend__vgKKq{margin-top:1rem}.line-chart-module_line-chart__ITM3d{display:flex;flex-direction:column}.line-chart-module_line-chart__ITM3d svg{overflow:visible}.line-chart-module_line-chart__annotation-label-popover__TqNZk,.line-chart-module_line-chart__tooltip__aqcme{background:#fff;padding:.5rem}.line-chart-module_line-chart__tooltip-date__4Dzab{font-weight:700;padding-bottom:10px}.line-chart-module_line-chart__tooltip-row__6A37G{align-items:center;display:flex;justify-content:space-between;padding:4px 0}.line-chart-module_line-chart__tooltip-label__IvnFF{font-weight:500;padding-right:1rem}.line-chart-module_line-chart__annotations-overlay__4nR2p{left:0;overflow:visible;pointer-events:none;position:absolute;top:0}.line-chart-module_line-chart__annotation-label__OmgiT{pointer-events:auto}.line-chart-module_line-chart__annotation-label-trigger-button__mcIb3{align-items:center;background:none;border:none;cursor:pointer;display:flex;justify-content:center;padding:0;pointer-events:auto}.line-chart-module_line-chart__annotation-label-popover__TqNZk{background:#fff;border:none;border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,.1);font-size:14px;margin:.5rem;min-width:125px;position:fixed;visibility:hidden}.line-chart-module_line-chart__annotation-label-popover--visible__dE0cV{visibility:visible}.line-chart-module_line-chart__annotation-label-popover--safari__i3NHT{margin:auto;position:static}.line-chart-module_line-chart__annotation-label-popover-header__Owypo{align-items:start;display:flex;flex-direction:row;justify-content:space-between}.line-chart-module_line-chart__annotation-label-popover-content__vtgQt{padding:.5rem}.line-chart-module_line-chart__annotation-label-popover-close-button__i8KUc{align-items:center;background:none;border:none;cursor:pointer;display:flex;height:44px;justify-content:center;padding:0;width:44px}.visx-tooltip-glyph svg{height:10px;width:10px}.base-tooltip-module_tooltip__OfX6n{background-color:rgba(0,0,0,.85);border-radius:4px;box-shadow:0 1px 2px rgba(0,0,0,.1);color:#fff;font-size:14px;padding:.5rem;pointer-events:none;position:absolute;transform:translate(-50%,-100%)}.pie-chart-module_pie-chart__R12Vh{display:flex;flex-direction:column;overflow:hidden}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9{display:flex;flex-direction:column;text-align:center}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9 .pie-semi-circle-chart-module_label__nPqOg{font-size:16px;font-weight:600;margin-bottom:0}.pie-semi-circle-chart-module_pie-semi-circle-chart__r5jk9 .pie-semi-circle-chart-module_note__LpBZQ{font-size:14px;margin-top:0}.leaderboard-chart-module_leaderboardChart__zxakP{transition:opacity .3s ease-in-out}.leaderboard-chart-module_leaderboardChart__zxakP.leaderboard-chart-module_loading__-AGv-{opacity:.5}.leaderboard-chart-module_progressContainerWithOverlayLabel__YFPY0{align-items:center;display:grid;grid-template:"overlap" 1fr/1fr}.leaderboard-chart-module_progressContainerWithOverlayLabel__YFPY0>*{grid-area:overlap}.leaderboard-chart-module_progressContainerWithOverlayLabel__YFPY0 .leaderboard-chart-module_progressBar__LAQaj{background-color:var(--primary-color,#3858e9);border-radius:var(--bar-border,9999px);height:100%;transition:width .3s ease-in-out;z-index:-1}.leaderboard-chart-module_progressContainerWithOverlayLabel__YFPY0 .leaderboard-chart-module_progressBarLabel__24t-j{padding-left:8px}.leaderboard-chart-module_progressContainer__BZGbj{display:flex;flex-direction:column;gap:6px}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_progressBar__LAQaj{background-color:transparent;border-radius:2px;height:6px;overflow:hidden;transition:width .3s ease-in-out;width:100%}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_progressBar__LAQaj>div{background-color:var(--progress-color,#3858e9);border-radius:var(--bar-border,9999px)}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_primaryBar__iybII{--progress-color:var(--primary-color,#3858e9)}.leaderboard-chart-module_progressContainer__BZGbj .leaderboard-chart-module_secondaryBar__A7tLz{--progress-color:var(--secondary-color,#66bdff)}.leaderboard-chart-module_valueContainer__ZlLh4{display:flex;gap:4px;justify-content:flex-end}.leaderboard-chart-module_overlayLabel__pRqSh{align-items:center}.leaderboard-chart-module_emptyState__0dkfy{color:#666;font-size:14px;font-style:italic;padding:32px 16px;text-align:center}

package/dist/mjs/utils/merge-themes.js

@@ -0,0 +1,19 @@
+import deepmerge from 'deepmerge';
+
+/**
+ * Merges chart themes with proper precedence.
+ * The second theme (override) takes precedence over the first theme (base).
+ *
+ * @param baseTheme     - Base theme object
+ * @param overrideTheme - Theme to override base with (takes precedence)
+ * @return Merged theme with overrideTheme values taking precedence
+ */
+function mergeThemes(baseTheme, overrideTheme) {
+    // Use deepmerge to properly merge nested objects, with overrideTheme taking precedence
+    return deepmerge(baseTheme, overrideTheme, {
+        // Ensure arrays are replaced rather than concatenated
+        arrayMerge: (_destinationArray, sourceArray) => sourceArray,
+    });
+}
+
+export { mergeThemes };

package/dist/types/components/bar-list-chart/bar-list-chart.d.ts

@@ -67,6 +67,6 @@ interface RenderValueProps {
     index: number;
     formatter: (value: number) => string;
 }
-declare const _default: ({ resizeDebounceTime, maxWidth, aspectRatio, ...chartProps }: Pick<Partial<BarListChartProps>, "height" | "size" | "width"> & Omit<BarListChartProps, "height" | "size" | "width"> & ResponsiveConfig) => react_jsx_runtime.JSX.Element;
+declare const _default: ({ resizeDebounceTime, maxWidth, aspectRatio, ...chartProps }: Pick<Partial<BarListChartProps>, "width" | "height" | "size"> & Omit<BarListChartProps, "width" | "height" | "size"> & ResponsiveConfig) => react_jsx_runtime.JSX.Element;
 
 export { _default as default };

package/dist/types/components/leaderboard-chart/leaderboard-chart.d.ts

@@ -6,9 +6,9 @@ interface LeaderboardEntry {
      */
     id: string;
     /**
-     * Human-readable name (e.g., 'Direct')
+     * Human-readable name (e.g., 'Direct') or a JSX element (e.g., <h4>Direct</h4>)
      */
-    label: string;
+    label: string | JSX.Element;
     /**
      * Value of the entry
      */
@@ -39,6 +39,10 @@ interface LeaderboardChartProps {
      * Whether to show comparison data
      */
     withComparison?: boolean;
+    /**
+     * Whether to overlay the label on top of bar
+     */
+    withOverlayLabel?: boolean;
     /**
      * Primary color for current period bars
      */
@@ -66,22 +70,27 @@ interface LeaderboardChartProps {
     /**
      * Custom styling for the chart container
      */
-    style?: React.CSSProperties;
+    style?: React.CSSProperties & {
+        '--bar-border'?: string;
+        '--primary-color'?: string;
+        '--secondary-color'?: string;
+    };
 }
 /**
  * LeaderboardChart component displays a ranked list of data with progress bars
  * and optional comparison values.
  *
- * @param props                - Component props
- * @param props.data           - Array of leaderboard entries to display
- * @param props.withComparison - Whether to show comparison data
- * @param props.primaryColor   - Primary color for current period bars
- * @param props.secondaryColor - Secondary color for comparison period bars
- * @param props.valueFormatter - Custom formatter for values
- * @param props.deltaFormatter - Custom formatter for delta values
- * @param props.loading        - Whether the chart is in loading state
- * @param props.className      - Additional CSS class name
- * @param props.style          - Custom styling for the chart container
+ * @param props                  - Component props
+ * @param props.data             - Array of leaderboard entries to display
+ * @param props.withComparison   - Whether to show comparison data
+ * @param props.withOverlayLabel - Whether to overlay the label on top of the bar
+ * @param props.primaryColor     - Primary color for current period bars
+ * @param props.secondaryColor   - Secondary color for comparison period bars
+ * @param props.valueFormatter   - Custom formatter for values
+ * @param props.deltaFormatter   - Custom formatter for delta values
+ * @param props.loading          - Whether the chart is in loading state
+ * @param props.className        - Additional CSS class name
+ * @param props.style            - Custom styling for the chart container
  * @return JSX element representing the leaderboard chart
  */
 declare const LeaderboardChart: FC<LeaderboardChartProps>;

package/dist/types/components/legend/base-legend.d.ts

@@ -10,15 +10,21 @@ declare const BaseLegend: react.ForwardRefExoticComponent<Omit<{
         text: string;
         value?: any;
     }[]) => React.ReactNode;
-    shape?: _visx_legend_lib_types.LegendShape<unknown, any>;
+    className?: string;
+    style?: React.CSSProperties;
+    fill?: (label: {
+        datum: unknown;
+        index: number;
+        text: string;
+        value?: any;
+    }) => string | undefined;
     size?: (label: {
         datum: unknown;
         index: number;
         text: string;
         value?: any;
     }) => string | number | undefined;
-    className?: string;
-    style?: React.CSSProperties;
+    shape?: _visx_legend_lib_types.LegendShape<unknown, any>;
     domain?: unknown[];
     shapeWidth?: string | number;
     shapeHeight?: string | number;
@@ -28,12 +34,6 @@ declare const BaseLegend: react.ForwardRefExoticComponent<Omit<{
     labelMargin?: string | number;
     itemMargin?: string | number;
     itemDirection?: _visx_legend_lib_types.FlexDirection;
-    fill?: (label: {
-        datum: unknown;
-        index: number;
-        text: string;
-        value?: any;
-    }) => string | undefined;
     shapeStyle?: (label: {
         datum: unknown;
         index: number;

package/dist/types/components/legend/use-chart-legend-data.d.ts

@@ -1,5 +1,5 @@
 import { LegendItemWithGlyph, LegendItemWithoutGlyph } from './types.js';
-import { SeriesData, DataPointDate, DataPointPercentage, ChartTheme } from '../../types.js';
+import { SeriesData, DataPointDate, DataPointPercentage } from '../../types.js';
 import { LegendShape } from '@visx/legend/lib/types';
 
 interface ChartLegendOptions {
@@ -11,11 +11,10 @@ interface ChartLegendOptions {
 /**
  * Hook to transform chart data into legend items
  * @param data        - The chart data to transform
- * @param theme       - The chart theme for colors
  * @param options     - Configuration options for legend generation
  * @param legendShape - The shape type for legend items (string literal or React component)
  * @return Array of legend items ready for display
  */
-declare function useChartLegendData<T extends SeriesData[] | DataPointDate[] | DataPointPercentage[]>(data: T, theme: ChartTheme, options?: ChartLegendOptions, legendShape?: LegendShape<SeriesData[], number>): LegendItemWithGlyph[] | LegendItemWithoutGlyph[];
+declare function useChartLegendData<T extends SeriesData[] | DataPointDate[] | DataPointPercentage[]>(data: T, options?: ChartLegendOptions, legendShape?: LegendShape<SeriesData[], number>): LegendItemWithGlyph[] | LegendItemWithoutGlyph[];
 
 export { type ChartLegendOptions, useChartLegendData };

package/dist/types/components/pie-chart/index.d.ts

@@ -1 +1 @@
-export { default as PieChart } from './pie-chart.js';
+export { default as PieChart, PieChartUnresponsive } from './pie-chart.js';

package/dist/types/components/pie-chart/pie-chart.d.ts

@@ -1,7 +1,7 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Legend } from '../legend/legend.js';
+import { FC, ComponentType, PropsWithChildren, ReactNode } from 'react';
+import { Optional, BaseChartProps, DataPointPercentage } from '../../types.js';
 import { ResponsiveConfig } from '../shared/with-responsive.js';
-import { BaseChartProps, DataPointPercentage } from '../../types.js';
-import { ReactNode } from 'react';
 
 interface PieChartProps extends BaseChartProps<DataPointPercentage[]> {
     /**
@@ -33,6 +33,15 @@ interface PieChartProps extends BaseChartProps<DataPointPercentage[]> {
      */
     children?: ReactNode;
 }
-declare const _default: ({ resizeDebounceTime, maxWidth, aspectRatio, ...chartProps }: Pick<Partial<PieChartProps>, "height" | "size" | "width"> & Omit<PieChartProps, "height" | "size" | "width"> & ResponsiveConfig) => react_jsx_runtime.JSX.Element;
+type PieChartBaseProps = Optional<PieChartProps, 'size'>;
+interface PieChartSubComponents {
+    Legend: ComponentType<React.ComponentProps<typeof Legend>>;
+    SVG: FC<PropsWithChildren>;
+    HTML: FC<PropsWithChildren>;
+}
+type PieChartComponent = FC<PieChartBaseProps> & PieChartSubComponents;
+type PieChartResponsiveComponent = FC<PieChartBaseProps & ResponsiveConfig> & PieChartSubComponents;
+declare const PieChart: PieChartComponent;
+declare const PieChartResponsive: PieChartResponsiveComponent;
 
-export { _default as default };
+export { PieChart as PieChartUnresponsive, PieChartResponsive as default };

package/dist/types/components/pie-semi-circle-chart/pie-semi-circle-chart.d.ts

@@ -1,6 +1,7 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Legend } from '../legend/legend.js';
+import { FC, ComponentType, PropsWithChildren, ReactNode } from 'react';
+import { Optional, BaseChartProps, DataPointPercentage } from '../../types.js';
 import { ResponsiveConfig } from '../shared/with-responsive.js';
-import { BaseChartProps, DataPointPercentage } from '../../types.js';
 
 interface PieSemiCircleChartProps extends BaseChartProps<DataPointPercentage[]> {
     /**
@@ -24,7 +25,18 @@ interface PieSemiCircleChartProps extends BaseChartProps<DataPointPercentage[]>
      * Note text to display below the label
      */
     note?: string;
+    /**
+     * Use the children prop to render additional elements on the chart.
+     */
+    children?: ReactNode;
+}
+type PieSemiCircleChartBaseProps = Optional<PieSemiCircleChartProps, 'width'>;
+interface PieSemiCircleChartSubComponents {
+    Legend: ComponentType<React.ComponentProps<typeof Legend>>;
+    SVG: FC<PropsWithChildren>;
+    HTML: FC<PropsWithChildren>;
 }
-declare const _default: ({ resizeDebounceTime, maxWidth, aspectRatio, ...chartProps }: Pick<Partial<PieSemiCircleChartProps>, "height" | "size" | "width"> & Omit<PieSemiCircleChartProps, "height" | "size" | "width"> & ResponsiveConfig) => react_jsx_runtime.JSX.Element;
+type PieSemiCircleChartResponsiveComponent = FC<PieSemiCircleChartBaseProps & ResponsiveConfig> & PieSemiCircleChartSubComponents;
+declare const PieSemiCircleChartResponsive: PieSemiCircleChartResponsiveComponent;
 
-export { _default as default };
+export { PieSemiCircleChartResponsive as default };

package/dist/types/hooks/use-chart-mouse-handler.d.ts

@@ -41,4 +41,4 @@ type UseChartMouseHandlerReturn = {
  */
 declare const useChartMouseHandler: ({ withTooltips, }: UseChartMouseHandlerProps) => UseChartMouseHandlerReturn;
 
-export { useChartMouseHandler as default };
+export { useChartMouseHandler };

package/dist/types/hooks/use-deep-memo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Custom hook to memoize a value using deep equality comparison.
+ * Prevents unnecessary re-renders when objects have the same content but different references.
+ *
+ * @param value - The value to memoize with deep equality comparison
+ * @return The memoized value that only changes when deeply different
+ */
+declare const useDeepMemo: <T>(value: T) => T;
+
+export { useDeepMemo };

package/dist/types/hooks/use-global-chart-theme.d.ts

@@ -0,0 +1,14 @@
+import { ChartTheme } from '../types.js';
+
+/**
+ * Hook to get the effective chart theme, merging global and local themes.
+ *
+ * This hook combines the global theme from GlobalChartsProvider with the local theme
+ * from ThemeProvider. The global theme provides the base, while the local theme
+ * can override specific properties for fine-grained customization.
+ *
+ * @return The effective chart theme to use
+ */
+declare const useGlobalChartTheme: () => ChartTheme;
+
+export { useGlobalChartTheme };

package/dist/types/hooks/use-xychart-theme.d.ts

@@ -0,0 +1,6 @@
+import * as _visx_xychart from '@visx/xychart';
+import { SeriesData } from '../types.js';
+
+declare const useXYChartTheme: (data: SeriesData[]) => _visx_xychart.XYChartTheme;
+
+export { useXYChartTheme };

package/dist/types/index.d.ts

@@ -15,7 +15,11 @@ export { Group } from '@visx/group';
 export { CircleShape, LineShape, RectShape } from '@visx/legend';
 export { ThemeProvider } from './providers/theme/theme-provider.js';
 export { defaultTheme, jetpackTheme, wooTheme } from './providers/theme/themes.js';
-export { default as useChartMouseHandler } from './hooks/use-chart-mouse-handler.js';
+export { mergeThemes } from './utils/merge-themes.js';
+export { useDeepMemo } from './hooks/use-deep-memo.js';
+export { useGlobalChartTheme } from './hooks/use-global-chart-theme.js';
+export { useChartMouseHandler } from './hooks/use-chart-mouse-handler.js';
+export { useXYChartTheme } from './hooks/use-xychart-theme.js';
 export { BaseChartProps, ButtonWithPopover, ChartTheme, DataPoint, DataPointDate, DataPointPercentage, GridProps, MultipleDataPointsDate, Optional, OrientationType, PopoverButtonAttributes, PopoverElement, PopoverElementAttributes, ScaleOptions, SeriesData, SeriesDataOptions, ToggleEvent } from './types.js';
 export { RenderTooltipParams } from '@visx/xychart/lib/components/Tooltip';
 export { EventHandlerParams, GridStyles, LineStyles } from '@visx/xychart';

package/dist/types/providers/chart-context/global-charts-provider.d.ts

@@ -1,10 +1,13 @@
 import * as react from 'react';
 import { FC, ReactNode } from 'react';
 import { ChartContextValue } from './types.js';
+import { ChartTheme } from '../../types.js';
 
 declare const GlobalChartsContext: react.Context<ChartContextValue>;
 interface GlobalChartsProviderProps {
     children: ReactNode;
+    /** Optional theme override. Considered static for provider lifecycle. */
+    theme?: Partial<ChartTheme>;
 }
 declare const GlobalChartsProvider: FC<GlobalChartsProviderProps>;
 declare const useGlobalChartsContext: () => ChartContextValue;

package/dist/types/providers/chart-context/types.d.ts

@@ -3,7 +3,6 @@ import { ChartTheme } from '../../types.js';
 
 interface ChartRegistration {
     legendItems: BaseLegendItem[];
-    theme: ChartTheme;
     chartType: string;
     metadata?: Record<string, unknown>;
 }
@@ -12,6 +11,8 @@ interface ChartContextValue {
     registerChart: (id: string, data: ChartRegistration) => void;
     unregisterChart: (id: string) => void;
     getChartData: (id: string) => ChartRegistration | undefined;
+    /** Theme provided by the GlobalChartsProvider (merged with defaults) */
+    theme: ChartTheme;
 }
 
 export type { ChartContextValue, ChartRegistration };

package/dist/types/providers/chart-context/utils.d.ts

@@ -1,7 +1,12 @@
 import { BaseLegendItem } from '../../components/legend/types.js';
-import { ChartTheme } from '../../types.js';
 
 declare const useChartId: (providedId?: string) => string;
-declare const useChartRegistration: (chartId: string, legendItems: BaseLegendItem[], theme: ChartTheme, chartType: string, isDataValid: boolean, metadata?: Record<string, unknown>) => void;
+declare const useChartRegistration: ({ chartId, legendItems, chartType, isDataValid, metadata, }: {
+    chartId: string;
+    legendItems: BaseLegendItem[];
+    chartType: string;
+    isDataValid: boolean;
+    metadata?: Record<string, unknown>;
+}) => void;
 
 export { useChartId, useChartRegistration };

package/dist/types/providers/theme/index.d.ts

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

package/dist/types/providers/theme/theme-provider.d.ts

@@ -1,13 +1,11 @@
-import * as _visx_xychart from '@visx/xychart';
-import { ChartTheme, SeriesData } from '../../types.js';
+import { ChartTheme } from '../../types.js';
 import { FC, ReactNode } from 'react';
 
 /**
  * Hook to access chart theme
  * @return {object} A built theme configuration compatible with visx charts
  */
-declare const useChartTheme: () => ChartTheme;
-declare const useXYChartTheme: (data: SeriesData[]) => _visx_xychart.XYChartTheme;
+declare const useChartTheme: () => Partial<ChartTheme>;
 /**
  * Props for the ThemeProvider component
  */
@@ -19,4 +17,4 @@ type ThemeProviderProps = {
 };
 declare const ThemeProvider: FC<ThemeProviderProps>;
 
-export { ThemeProvider, useChartTheme, useXYChartTheme };
+export { ThemeProvider, useChartTheme };

package/dist/types/utils/merge-themes.d.ts

@@ -0,0 +1,13 @@
+import { ChartTheme } from '../types.js';
+
+/**
+ * Merges chart themes with proper precedence.
+ * The second theme (override) takes precedence over the first theme (base).
+ *
+ * @param baseTheme     - Base theme object
+ * @param overrideTheme - Theme to override base with (takes precedence)
+ * @return Merged theme with overrideTheme values taking precedence
+ */
+declare function mergeThemes(baseTheme: ChartTheme, overrideTheme: Partial<ChartTheme>): ChartTheme;
+
+export { mergeThemes };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "0.26.0",
+	"version": "0.28.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -80,6 +80,7 @@
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",
+		"fast-deep-equal": "3.1.3",
 		"gridicons": "3.4.2",
 		"tslib": "2.5.0"
 	},