@automattic/charts 0.57.0 → 0.58.0

package/dist/{types-DZordNiO.d.cts → types-ChOUI9-N.d.cts}

@@ -8,7 +8,7 @@ import { ScaleType, ScaleInput } from '@visx/scale';
 import { TextProps } from '@visx/text/lib/Text';
 import { EventHandlerParams, LineStyles, GridStyles, GlyphProps } from '@visx/xychart';
 import { GapSize } from '@wordpress/theme';
-import { PointerEvent, ReactNode, CSSProperties } from 'react';
+import { PointerEvent, CSSProperties, ReactNode } from 'react';
 import { GoogleDataTableColumn, GoogleDataTableRow } from 'react-google-charts';
 
 type ValueOf<T> = T[keyof T];
@@ -322,6 +322,81 @@ type ScaleOptions = {
      */
     paddingOuter?: number;
 };
+type LegendItemStyles = {
+    /** Margin around each legend item. */
+    margin?: CSSProperties['margin'];
+    /** Flex direction for items within each legend entry. */
+    flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+};
+type LegendLabelStyles = Pick<CSSProperties, 'justifyContent' | 'flex' | 'margin'> & {
+    /**
+     * Maximum width for legend label text as a CSS value (e.g. '200px', '50%', '10rem').
+     * When set, text overflow behavior is controlled by textOverflow.
+     */
+    maxWidth?: string;
+    /**
+     * Controls how text behaves when it exceeds maxWidth.
+     * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
+     * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
+     */
+    textOverflow?: 'ellipsis' | 'wrap';
+};
+type LegendShapeStyles = {
+    /** Width of the legend shape in pixels. */
+    width?: number;
+    /** Height of the legend shape in pixels. */
+    height?: number;
+    /** Margin around the legend shape. */
+    margin?: CSSProperties['margin'];
+};
+/** Position of the legend relative to chart content. */
+type LegendPosition = 'top' | 'bottom';
+/**
+ * Configuration object for chart legend appearance and behavior.
+ * Consolidates all legend styling and layout props into a single structured object.
+ */
+type ChartLegendConfig<T = DataPoint | DataPointDate | LeaderboardEntry> = {
+    /**
+     * Layout direction of legend items.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Position of the legend relative to the chart.
+     * TODO: Add 'left' | 'right' positioning support in future implementation
+     */
+    position?: LegendPosition;
+    /**
+     * Alignment of the legend within its position.
+     */
+    alignment?: 'start' | 'center' | 'end';
+    /**
+     * Shape of the legend marker icon.
+     */
+    shape?: LegendShape<T, number>;
+    /**
+     * Enable interactive legend items that can toggle series visibility.
+     * Supported for all chart types that render series.
+     * Requires chartId and GlobalChartsProvider.
+     * For pie charts, percentages are recalculated so visible segments total 100%.
+     */
+    interactive?: boolean;
+    /**
+     * Additional CSS class name for individual legend items.
+     */
+    itemClassName?: string;
+    /**
+     * CSS styles for each legend item (margin, flexDirection).
+     */
+    itemStyles?: LegendItemStyles;
+    /**
+     * CSS styles for legend labels (maxWidth, textOverflow, justifyContent, flex, margin).
+     */
+    labelStyles?: LegendLabelStyles;
+    /**
+     * Styles for legend shapes (width, height, margin).
+     */
+    shapeStyles?: LegendShapeStyles;
+};
 /**
  * Base properties shared across all chart components
  */
@@ -386,45 +461,10 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
      */
     showLegend?: boolean;
     /**
-     * Legend orientation
-     */
-    legendOrientation?: 'horizontal' | 'vertical';
-    /**
-     * Legend shape
-     */
-    legendShape?: LegendShape<T, number>;
-    /**
-     * Legend position (where the legend appears)
-     * TODO: Add 'left' | 'right' positioning support in future implementation
-     */
-    legendPosition?: 'top' | 'bottom';
-    /**
-     * Legend alignment within its position
-     */
-    legendAlignment?: 'start' | 'center' | 'end';
-    /**
-     * Maximum width for legend items. When set, text overflow behavior is controlled by legendTextOverflow.
-     * Should be a CSS value string (e.g. '200px', '50%', '10rem')
-     */
-    legendMaxWidth?: string;
-    /**
-     * Controls how text behaves when it exceeds legendMaxWidth.
-     * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
-     * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
-     */
-    legendTextOverflow?: 'ellipsis' | 'wrap';
-    /**
-     * Additional CSS class name for legend items.
-     * This allows consumers to customize individual legend item styling.
-     */
-    legendItemClassName?: string;
-    /**
-     * Enable interactive legend items that can toggle series visibility.
-     * Supported for all chart types that render series.
-     * Requires chartId and GlobalChartsProvider.
-     * For pie charts, percentages are recalculated so visible segments total 100%.
+     * Legend configuration object for controlling legend appearance and behavior.
+     * Includes orientation, position, alignment, shape, styling, and interactivity options.
      */
-    legendInteractive?: boolean;
+    legend?: ChartLegendConfig<T>;
     /**
      * Grid visibility. x is default when orientation is vertical. y is default when orientation is horizontal.
      */
@@ -502,4 +542,4 @@ interface ToggleEvent extends Event {
     oldState: 'open' | 'closed';
 }
 
-export type { AnnotationStyles as A, BaseChartProps as B, ChartTheme as C, DataPoint as D, GeoData as G, LeaderboardEntry as L, MultipleDataPointsDate as M, Optional as O, PopoverButtonAttributes as P, ScaleOptions as S, ToggleEvent as T, ButtonWithPopover as a, CompleteChartTheme as b, DataPointDate as c, DataPointPercentage as d, GradientStop as e, GridProps as f, OrientationType as g, PopoverElement as h, PopoverElementAttributes as i, SeriesData as j, SeriesDataOptions as k };
+export type { AnnotationStyles as A, BaseChartProps as B, ChartLegendConfig as C, DataPoint as D, GeoData as G, LeaderboardEntry as L, MultipleDataPointsDate as M, Optional as O, PopoverButtonAttributes as P, ScaleOptions as S, ToggleEvent as T, ButtonWithPopover as a, ChartTheme as b, CompleteChartTheme as c, DataPointDate as d, DataPointPercentage as e, GradientStop as f, GridProps as g, LegendItemStyles as h, LegendLabelStyles as i, LegendPosition as j, LegendShapeStyles as k, OrientationType as l, PopoverElement as m, PopoverElementAttributes as n, SeriesData as o, SeriesDataOptions as p };

package/dist/{types-DZordNiO.d.ts → types-ChOUI9-N.d.ts}

@@ -8,7 +8,7 @@ import { ScaleType, ScaleInput } from '@visx/scale';
 import { TextProps } from '@visx/text/lib/Text';
 import { EventHandlerParams, LineStyles, GridStyles, GlyphProps } from '@visx/xychart';
 import { GapSize } from '@wordpress/theme';
-import { PointerEvent, ReactNode, CSSProperties } from 'react';
+import { PointerEvent, CSSProperties, ReactNode } from 'react';
 import { GoogleDataTableColumn, GoogleDataTableRow } from 'react-google-charts';
 
 type ValueOf<T> = T[keyof T];
@@ -322,6 +322,81 @@ type ScaleOptions = {
      */
     paddingOuter?: number;
 };
+type LegendItemStyles = {
+    /** Margin around each legend item. */
+    margin?: CSSProperties['margin'];
+    /** Flex direction for items within each legend entry. */
+    flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
+};
+type LegendLabelStyles = Pick<CSSProperties, 'justifyContent' | 'flex' | 'margin'> & {
+    /**
+     * Maximum width for legend label text as a CSS value (e.g. '200px', '50%', '10rem').
+     * When set, text overflow behavior is controlled by textOverflow.
+     */
+    maxWidth?: string;
+    /**
+     * Controls how text behaves when it exceeds maxWidth.
+     * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
+     * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
+     */
+    textOverflow?: 'ellipsis' | 'wrap';
+};
+type LegendShapeStyles = {
+    /** Width of the legend shape in pixels. */
+    width?: number;
+    /** Height of the legend shape in pixels. */
+    height?: number;
+    /** Margin around the legend shape. */
+    margin?: CSSProperties['margin'];
+};
+/** Position of the legend relative to chart content. */
+type LegendPosition = 'top' | 'bottom';
+/**
+ * Configuration object for chart legend appearance and behavior.
+ * Consolidates all legend styling and layout props into a single structured object.
+ */
+type ChartLegendConfig<T = DataPoint | DataPointDate | LeaderboardEntry> = {
+    /**
+     * Layout direction of legend items.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Position of the legend relative to the chart.
+     * TODO: Add 'left' | 'right' positioning support in future implementation
+     */
+    position?: LegendPosition;
+    /**
+     * Alignment of the legend within its position.
+     */
+    alignment?: 'start' | 'center' | 'end';
+    /**
+     * Shape of the legend marker icon.
+     */
+    shape?: LegendShape<T, number>;
+    /**
+     * Enable interactive legend items that can toggle series visibility.
+     * Supported for all chart types that render series.
+     * Requires chartId and GlobalChartsProvider.
+     * For pie charts, percentages are recalculated so visible segments total 100%.
+     */
+    interactive?: boolean;
+    /**
+     * Additional CSS class name for individual legend items.
+     */
+    itemClassName?: string;
+    /**
+     * CSS styles for each legend item (margin, flexDirection).
+     */
+    itemStyles?: LegendItemStyles;
+    /**
+     * CSS styles for legend labels (maxWidth, textOverflow, justifyContent, flex, margin).
+     */
+    labelStyles?: LegendLabelStyles;
+    /**
+     * Styles for legend shapes (width, height, margin).
+     */
+    shapeStyles?: LegendShapeStyles;
+};
 /**
  * Base properties shared across all chart components
  */
@@ -386,45 +461,10 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
      */
     showLegend?: boolean;
     /**
-     * Legend orientation
-     */
-    legendOrientation?: 'horizontal' | 'vertical';
-    /**
-     * Legend shape
-     */
-    legendShape?: LegendShape<T, number>;
-    /**
-     * Legend position (where the legend appears)
-     * TODO: Add 'left' | 'right' positioning support in future implementation
-     */
-    legendPosition?: 'top' | 'bottom';
-    /**
-     * Legend alignment within its position
-     */
-    legendAlignment?: 'start' | 'center' | 'end';
-    /**
-     * Maximum width for legend items. When set, text overflow behavior is controlled by legendTextOverflow.
-     * Should be a CSS value string (e.g. '200px', '50%', '10rem')
-     */
-    legendMaxWidth?: string;
-    /**
-     * Controls how text behaves when it exceeds legendMaxWidth.
-     * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
-     * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
-     */
-    legendTextOverflow?: 'ellipsis' | 'wrap';
-    /**
-     * Additional CSS class name for legend items.
-     * This allows consumers to customize individual legend item styling.
-     */
-    legendItemClassName?: string;
-    /**
-     * Enable interactive legend items that can toggle series visibility.
-     * Supported for all chart types that render series.
-     * Requires chartId and GlobalChartsProvider.
-     * For pie charts, percentages are recalculated so visible segments total 100%.
+     * Legend configuration object for controlling legend appearance and behavior.
+     * Includes orientation, position, alignment, shape, styling, and interactivity options.
      */
-    legendInteractive?: boolean;
+    legend?: ChartLegendConfig<T>;
     /**
      * Grid visibility. x is default when orientation is vertical. y is default when orientation is horizontal.
      */
@@ -502,4 +542,4 @@ interface ToggleEvent extends Event {
     oldState: 'open' | 'closed';
 }
 
-export type { AnnotationStyles as A, BaseChartProps as B, ChartTheme as C, DataPoint as D, GeoData as G, LeaderboardEntry as L, MultipleDataPointsDate as M, Optional as O, PopoverButtonAttributes as P, ScaleOptions as S, ToggleEvent as T, ButtonWithPopover as a, CompleteChartTheme as b, DataPointDate as c, DataPointPercentage as d, GradientStop as e, GridProps as f, OrientationType as g, PopoverElement as h, PopoverElementAttributes as i, SeriesData as j, SeriesDataOptions as k };
+export type { AnnotationStyles as A, BaseChartProps as B, ChartLegendConfig as C, DataPoint as D, GeoData as G, LeaderboardEntry as L, MultipleDataPointsDate as M, Optional as O, PopoverButtonAttributes as P, ScaleOptions as S, ToggleEvent as T, ButtonWithPopover as a, ChartTheme as b, CompleteChartTheme as c, DataPointDate as d, DataPointPercentage as e, GradientStop as f, GridProps as g, LegendItemStyles as h, LegendLabelStyles as i, LegendPosition as j, LegendShapeStyles as k, OrientationType as l, PopoverElement as m, PopoverElementAttributes as n, SeriesData as o, SeriesDataOptions as p };

package/dist/{types-I67mddpr.d.ts → types-Dfw9VOKI.d.cts}

@@ -1,42 +1,13 @@
 import { LegendOrdinal } from '@visx/legend';
+import { j as LegendPosition, h as LegendItemStyles, i as LegendLabelStyles, k as LegendShapeStyles } from './types-ChOUI9-N.cjs';
 import { GlyphProps, LineStyles } from '@visx/xychart';
 import { ComponentProps, ReactNode, CSSProperties } from 'react';
 
 type VisxLegendProps = Pick<ComponentProps<typeof LegendOrdinal>, 'className' | 'shape' | 'fill' | 'size' | 'labelFormat' | 'labelTransform'>;
-type LegendItemStyles = {
-    /** Margin around each legend item. */
-    margin?: CSSProperties['margin'];
-    /** Flex direction for items within each legend entry. */
-    flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
-};
-type LegendLabelStyles = Pick<CSSProperties, 'justifyContent' | 'flex' | 'margin'> & {
-    /**
-     * Maximum width for legend label text as a CSS value (e.g. '200px', '50%', '10rem').
-     * When set, text overflow behavior is controlled by textOverflow.
-     */
-    maxWidth?: string;
-    /**
-     * Controls how text behaves when it exceeds maxWidth.
-     * - 'ellipsis': Truncate with ellipsis (ideal for widgets/small devices)
-     * - 'wrap': Wrap text to multiple lines (default, ideal for larger displays)
-     */
-    textOverflow?: 'ellipsis' | 'wrap';
-};
-type LegendShapeStyles = {
-    /** Width of the legend shape in pixels. */
-    width?: number;
-    /** Height of the legend shape in pixels. */
-    height?: number;
-    /** Margin around the legend shape. */
-    margin?: CSSProperties['margin'];
-};
 type BaseLegendProps = VisxLegendProps & {
     items: BaseLegendItem[];
     orientation?: 'horizontal' | 'vertical';
-    /**
-     * TODO: Add 'left' | 'right' positioning support in future implementation
-     */
-    position?: 'top' | 'bottom';
+    position?: LegendPosition;
     alignment?: 'start' | 'center' | 'end';
     /** Additional CSS class name for legend items. */
     itemClassName?: string;
@@ -75,4 +46,4 @@ type BaseLegendItem = {
     shapeStyle?: CSSProperties & LineStyles;
 };
 
-export type { BaseLegendItem as B, LegendItemStyles as L, LegendLabelStyles as a, LegendShapeStyles as b, BaseLegendProps as c, LegendProps as d };
+export type { BaseLegendItem as B, LegendProps as L, BaseLegendProps as a };

package/dist/utils/index.cjs

@@ -18,7 +18,7 @@
 
 
 
-var _chunkVTS3PNMScjs = require('../chunk-VTS3PNMS.cjs');
+var _chunkMXGLYWVPcjs = require('../chunk-MXGLYWVP.cjs');
 require('../chunk-EMMSS5I5.cjs');
 
 
@@ -40,5 +40,5 @@ require('../chunk-EMMSS5I5.cjs');
 
 
 
-exports.attachSubComponents = _chunkVTS3PNMScjs.attachSubComponents; exports.formatMetricValue = _chunkVTS3PNMScjs.formatMetricValue; exports.formatPercentage = _chunkVTS3PNMScjs.formatPercentage; exports.getColorDistance = _chunkVTS3PNMScjs.getColorDistance; exports.getItemShapeStyles = _chunkVTS3PNMScjs.getItemShapeStyles; exports.getLongestTickWidth = _chunkVTS3PNMScjs.getLongestTickWidth; exports.getSeriesLineStyles = _chunkVTS3PNMScjs.getSeriesLineStyles; exports.getSeriesStroke = _chunkVTS3PNMScjs.getSeriesStroke; exports.hexToRgba = _chunkVTS3PNMScjs.hexToRgba; exports.isSafari = _chunkVTS3PNMScjs.isSafari; exports.isValidHexColor = _chunkVTS3PNMScjs.isValidHexColor; exports.lightenHexColor = _chunkVTS3PNMScjs.lightenHexColor; exports.mergeThemes = _chunkVTS3PNMScjs.mergeThemes; exports.normalizeColorToHex = _chunkVTS3PNMScjs.normalizeColorToHex; exports.parseAsLocalDate = _chunkVTS3PNMScjs.parseAsLocalDate; exports.parseHslString = _chunkVTS3PNMScjs.parseHslString; exports.parseRgbString = _chunkVTS3PNMScjs.parseRgbString; exports.resolveCssVariable = _chunkVTS3PNMScjs.resolveCssVariable; exports.validateHexColor = _chunkVTS3PNMScjs.validateHexColor;
+exports.attachSubComponents = _chunkMXGLYWVPcjs.attachSubComponents; exports.formatMetricValue = _chunkMXGLYWVPcjs.formatMetricValue; exports.formatPercentage = _chunkMXGLYWVPcjs.formatPercentage; exports.getColorDistance = _chunkMXGLYWVPcjs.getColorDistance; exports.getItemShapeStyles = _chunkMXGLYWVPcjs.getItemShapeStyles; exports.getLongestTickWidth = _chunkMXGLYWVPcjs.getLongestTickWidth; exports.getSeriesLineStyles = _chunkMXGLYWVPcjs.getSeriesLineStyles; exports.getSeriesStroke = _chunkMXGLYWVPcjs.getSeriesStroke; exports.hexToRgba = _chunkMXGLYWVPcjs.hexToRgba; exports.isSafari = _chunkMXGLYWVPcjs.isSafari; exports.isValidHexColor = _chunkMXGLYWVPcjs.isValidHexColor; exports.lightenHexColor = _chunkMXGLYWVPcjs.lightenHexColor; exports.mergeThemes = _chunkMXGLYWVPcjs.mergeThemes; exports.normalizeColorToHex = _chunkMXGLYWVPcjs.normalizeColorToHex; exports.parseAsLocalDate = _chunkMXGLYWVPcjs.parseAsLocalDate; exports.parseHslString = _chunkMXGLYWVPcjs.parseHslString; exports.parseRgbString = _chunkMXGLYWVPcjs.parseRgbString; exports.resolveCssVariable = _chunkMXGLYWVPcjs.resolveCssVariable; exports.validateHexColor = _chunkMXGLYWVPcjs.validateHexColor;
 //# sourceMappingURL=index.cjs.map

package/dist/utils/index.d.cts

@@ -1,7 +1,7 @@
 export { M as MetricValueType, f as formatMetricValue } from '../format-metric-value-MXm5DtQ_.cjs';
 import { TickFormatter } from '@visx/axis';
 import { AnyD3Scale, ScaleInput } from '@visx/scale';
-import { j as SeriesData, C as ChartTheme, b as CompleteChartTheme } from '../types-DZordNiO.cjs';
+import { o as SeriesData, b as ChartTheme, c as CompleteChartTheme } from '../types-ChOUI9-N.cjs';
 import { LegendShape } from '@visx/legend/lib/types';
 import { LineStyles } from '@visx/xychart';
 import '@visx/annotation/lib/components/CircleSubject';

package/dist/utils/index.d.ts

@@ -1,7 +1,7 @@
 export { M as MetricValueType, f as formatMetricValue } from '../format-metric-value-MXm5DtQ_.js';
 import { TickFormatter } from '@visx/axis';
 import { AnyD3Scale, ScaleInput } from '@visx/scale';
-import { j as SeriesData, C as ChartTheme, b as CompleteChartTheme } from '../types-DZordNiO.js';
+import { o as SeriesData, b as ChartTheme, c as CompleteChartTheme } from '../types-ChOUI9-N.js';
 import { LegendShape } from '@visx/legend/lib/types';
 import { LineStyles } from '@visx/xychart';
 import '@visx/annotation/lib/components/CircleSubject';

package/dist/utils/index.js

@@ -18,7 +18,7 @@ import {
   parseRgbString,
   resolveCssVariable,
   validateHexColor
-} from "../chunk-DAU3HNEG.js";
+} from "../chunk-JJIMABHT.js";
 import "../chunk-G3PMV62Z.js";
 export {
   attachSubComponents,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/charts",
-	"version": "0.57.0",
+	"version": "0.58.0",
 	"description": "Display charts within Automattic products.",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/charts/#readme",
 	"bugs": {
@@ -180,7 +180,7 @@
 		"typecheck": "tsgo --noEmit"
 	},
 	"dependencies": {
-		"@automattic/number-formatters": "^1.1.1",
+		"@automattic/number-formatters": "^1.1.2",
 		"@babel/runtime": "7.28.6",
 		"@react-spring/web": "9.7.5",
 		"@visx/annotation": "^3.12.0",
@@ -200,8 +200,8 @@
 		"@visx/vendor": "^3.12.0",
 		"@visx/xychart": "^3.12.0",
 		"@wordpress/i18n": "^6.0.0",
-		"@wordpress/theme": "0.7.0",
-		"@wordpress/ui": "0.7.0",
+		"@wordpress/theme": "0.8.0",
+		"@wordpress/ui": "0.8.0",
 		"clsx": "2.1.1",
 		"date-fns": "^4.1.0",
 		"deepmerge": "4.3.1",
@@ -226,8 +226,8 @@
 		"@types/react-dom": "18.3.7",
 		"@typescript/native-preview": "7.0.0-dev.20260225.1",
 		"@visx/glyph": "3.12.0",
-		"@wordpress/components": "32.2.0",
-		"@wordpress/element": "6.40.0",
+		"@wordpress/components": "32.3.0",
+		"@wordpress/element": "6.41.0",
 		"babel-jest": "30.2.0",
 		"babel-plugin-react-remove-properties": "^0.3.1",
 		"esbuild": "0.25.9",

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

@@ -13,7 +13,6 @@ import {
 	useZeroValueDisplay,
 	useChartMargin,
 	useElementSize,
-	useHasLegendChild,
 	usePrefersReducedMotion,
 } from '../../hooks';
 import {
@@ -25,6 +24,7 @@ import {
 	GlobalChartsContext,
 } from '../../providers';
 import { attachSubComponents } from '../../utils';
+import { useChartChildren, renderLegendSlot } from '../private/chart-composition';
 import { SingleChartContext } from '../private/single-chart-context';
 import { withResponsive } from '../private/with-responsive';
 import styles from './bar-chart.module.scss';
@@ -39,7 +39,6 @@ export interface BarChartProps extends BaseChartProps< SeriesData[] > {
 	orientation?: 'horizontal' | 'vertical';
 	withPatterns?: boolean;
 	showZeroValues?: boolean;
-	legendInteractive?: boolean;
 	children?: ReactNode;
 }
 
@@ -85,24 +84,18 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	margin,
 	withTooltips = false,
 	showLegend = false,
-	legendOrientation = 'horizontal',
-	legendPosition = 'bottom',
-	legendAlignment = 'center',
-	legendMaxWidth,
-	legendTextOverflow = 'wrap',
-	legendItemClassName,
-	legendShape = 'rect',
+	legend = {},
 	gridVisibility: gridVisibilityProp,
 	renderTooltip,
 	options = {},
 	orientation = 'vertical',
 	withPatterns = false,
 	showZeroValues = false,
-	legendInteractive = false,
 	animation,
 	children,
 	gap = 'md',
 } ) => {
+	const legendInteractive = legend.interactive ?? false;
 	const horizontal = orientation === 'horizontal';
 	const chartId = useChartId( providedChartId );
 	const theme = useXYChartTheme( data );
@@ -123,8 +116,9 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const [ svgWrapperRef, , svgWrapperHeight ] = useElementSize< HTMLDivElement >();
 	const chartRef = useRef< HTMLDivElement >( null );
 
-	// Check if children contain a Legend component (composition pattern)
-	const hasLegendChild = useHasLegendChild( children );
+	// Process children for composition API (Legend, etc.)
+	const { legendChildren, nonLegendChildren } = useChartChildren( children, 'BarChart' );
+	const hasLegendChild = legendChildren.length > 0;
 
 	// Use the measured SVG wrapper height, falling back to the passed height if provided.
 	// When there's a legend (via prop or composition), we must wait for measurement because
@@ -327,15 +321,18 @@ const BarChartInternal: FC< BarChartProps > = ( {
 	const gridVisibility = gridVisibilityProp ?? chartOptions.gridVisibility;
 	const highlightedBarStyle = createKeyboardHighlightStyle();
 
+	const legendPosition = legend.position ?? 'bottom';
 	const legendElement = showLegend && (
 		<Legend
-			orientation={ legendOrientation }
+			orientation={ legend.orientation ?? 'horizontal' }
 			position={ legendPosition }
-			alignment={ legendAlignment }
-			labelStyles={ { maxWidth: legendMaxWidth, textOverflow: legendTextOverflow } }
-			itemClassName={ legendItemClassName }
+			alignment={ legend.alignment ?? 'center' }
+			labelStyles={ legend.labelStyles }
+			itemClassName={ legend.itemClassName }
+			itemStyles={ legend.itemStyles }
+			shapeStyles={ legend.shapeStyles }
 			className={ styles[ 'bar-chart__legend' ] }
-			shape={ legendShape }
+			shape={ legend.shape ?? 'rect' }
 			chartId={ chartId }
 			interactive={ legendInteractive }
 		/>
@@ -370,6 +367,7 @@ const BarChartInternal: FC< BarChartProps > = ( {
 				data-chart-id={ `bar-chart-${ chartId }` }
 			>
 				{ legendPosition === 'top' && legendElement }
+				{ renderLegendSlot( legendChildren, 'top' ) }
 
 				<div
 					className={ styles[ 'bar-chart__svg-wrapper' ] }
@@ -483,8 +481,9 @@ const BarChartInternal: FC< BarChartProps > = ( {
 				</div>
 
 				{ legendPosition === 'bottom' && legendElement }
+				{ renderLegendSlot( legendChildren, 'bottom' ) }
 
-				{ children }
+				{ nonLegendChildren }
 			</Stack>
 		</SingleChartContext.Provider>
 	);

package/src/charts/bar-chart/test/bar-chart.test.tsx

@@ -26,10 +26,12 @@ describe( 'BarChart', () => {
 		],
 	};
 
-	const renderWithTheme = ( props = {} ) => {
+	const renderWithTheme = ( props = {}, children = undefined ) => {
 		return render(
 			<GlobalChartsProvider>
-				<BarChart { ...defaultProps } { ...props } />
+				<BarChart { ...defaultProps } { ...props }>
+					{ children }
+				</BarChart>
 			</GlobalChartsProvider>
 		);
 	};
@@ -123,39 +125,54 @@ describe( 'BarChart', () => {
 	} );
 
 	describe( 'Legend', () => {
+		const multiSeriesData = [
+			{
+				label: 'Series A',
+				data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
+				options: {},
+			},
+			{
+				label: 'Series B',
+				data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
+				options: {},
+			},
+		];
+
 		test( 'shows legend when showLegend is true', () => {
-			renderWithTheme( {
-				showLegend: true,
-				data: [
-					{
-						label: 'Series A',
-						data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
-						options: {},
-					},
-					{
-						label: 'Series B',
-						data: [ { date: new Date( '2024-01-01' ), value: 20, label: 'Jan 1' } ],
-						options: {},
-					},
-				],
-			} );
+			renderWithTheme( { showLegend: true, data: multiSeriesData } );
 			expect( screen.getByText( 'Series A' ) ).toBeInTheDocument();
 			expect( screen.getByText( 'Series B' ) ).toBeInTheDocument();
 		} );
 
 		test( 'hides legend when showLegend is false', () => {
-			renderWithTheme( {
-				showLegend: false,
-				data: [
-					{
-						label: 'Series A',
-						data: [ { date: new Date( '2024-01-01' ), value: 10, label: 'Jan 1' } ],
-						options: {},
-					},
-				],
-			} );
+			renderWithTheme( { showLegend: false, data: multiSeriesData } );
 			expect( screen.queryByText( 'Series A' ) ).not.toBeInTheDocument();
 		} );
+
+		test( 'renders composition legend as child component', () => {
+			renderWithTheme( { data: multiSeriesData }, <BarChart.Legend /> );
+
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+			expect( screen.getByText( 'Series A' ) ).toBeInTheDocument();
+			expect( screen.getByText( 'Series B' ) ).toBeInTheDocument();
+		} );
+
+		test( 'renders composition legend regardless of showLegend value', () => {
+			renderWithTheme( { data: multiSeriesData, showLegend: false }, <BarChart.Legend /> );
+
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+		} );
+
+		test( 'renders composition legend in top position', () => {
+			renderWithTheme( { data: multiSeriesData }, <BarChart.Legend position="top" /> );
+
+			// Legend should appear before the chart content in DOM order
+			expect( screen.getAllByTestId( 'legend-item' ) ).toHaveLength( 2 );
+			const html = document.body.innerHTML;
+			expect( html.indexOf( 'data-testid="legend-horizontal"' ) ).toBeLessThan(
+				html.indexOf( 'role="grid"' )
+			);
+		} );
 	} );
 
 	describe( 'Grid Visibility', () => {
@@ -743,7 +760,7 @@ describe( 'BarChart', () => {
 
 			renderWithTheme( {
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-interactive-bar-chart',
 				data: [
 					{
@@ -771,7 +788,7 @@ describe( 'BarChart', () => {
 		it( 'does not filter series when legendInteractive is false', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendInteractive: false,
+				legend: { interactive: false },
 				chartId: 'test-non-interactive-bar-chart',
 				data: [
 					{
@@ -795,7 +812,7 @@ describe( 'BarChart', () => {
 		it( 'shows all series when chartId is missing even if legendInteractive is true', () => {
 			renderWithTheme( {
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				// No chartId provided
 				data: [
 					{
@@ -823,7 +840,7 @@ describe( 'BarChart', () => {
 
 			renderWithTheme( {
 				showLegend: true,
-				legendInteractive: true,
+				legend: { interactive: true },
 				chartId: 'test-all-hidden-bar-chart',
 				data: [
 					{