[charts] Add barLabel to bar series. Deprecate barLabel in BarPlot.

docs/data/charts/bars/BarLabel.js

@@ -1,12 +1,24 @@
 import { BarChart } from '@mui/x-charts/BarChart';
 
+const dollarFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0,
+});
+
 export default function BarLabel() {
   return (
     <BarChart
       xAxis={[{ data: ['group A', 'group B', 'group C'] }]}
-      series={[{ data: [4, 3, 5] }, { data: [1, 6, 3] }, { data: [2, 5, 6] }]}
+      series={[
+        { data: [4, 3, 5], barLabel: 'value' },
+        {
+          data: [1, 6, 3],
+          barLabel: (item) => dollarFormatter.format(item.value),
+        },
+        { data: [2, 5, 6] },
+      ]}
       height={300}
-      barLabel="value"
       margin={{ left: 0 }}
       yAxis={[{ width: 30 }]}
     />

docs/data/charts/bars/BarLabel.tsx

@@ -1,12 +1,24 @@
 import { BarChart } from '@mui/x-charts/BarChart';
 
+const dollarFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0,
+});
+
 export default function BarLabel() {
   return (
     <BarChart
       xAxis={[{ data: ['group A', 'group B', 'group C'] }]}
-      series={[{ data: [4, 3, 5] }, { data: [1, 6, 3] }, { data: [2, 5, 6] }]}
+      series={[
+        { data: [4, 3, 5], barLabel: 'value' },
+        {
+          data: [1, 6, 3],
+          barLabel: (item) => dollarFormatter.format(item.value!),
+        },
+        { data: [2, 5, 6] },
+      ]}
       height={300}
-      barLabel="value"
       margin={{ left: 0 }}
       yAxis={[{ width: 30 }]}
     />

docs/data/charts/bars/BarLabel.tsx.preview

@@ -1,8 +1,14 @@
 <BarChart
   xAxis={[{ data: ['group A', 'group B', 'group C'] }]}
-  series={[{ data: [4, 3, 5] }, { data: [1, 6, 3] }, { data: [2, 5, 6] }]}
+  series={[
+    { data: [4, 3, 5], barLabel: 'value' },
+    {
+      data: [1, 6, 3],
+      barLabel: (item) => dollarFormatter.format(item.value!),
+    },
+    { data: [2, 5, 6] },
+  ]}
   height={300}
-  barLabel="value"
   margin={{ left: 0 }}
   yAxis={[{ width: 30 }]}
 />

docs/data/charts/bars/bars.md

@@ -170,10 +170,12 @@
 
 ## Labels
 
-You can display labels on the bars.
-To do so, the `BarChart` or `BarPlot` accepts a `barLabel` prop.
-It can either get a function that gets the bar item and some context.
-Or you can pass `'value'` to display the raw value of the bar.
+You can display labels on the bars. This can be useful to show the value of each bar directly on the chart.
+
+If you provide `'value'` to the `barLabel` property of a bar series, the value of that bar is shown.
+Alternatively, the `barLabel` property accepts a function that is called with the bar item and context about the bar.
+
+In the example below, the value of the first series is displayed using the default formatter, and format the value of the second series as US dollars. The labels of the third series are hidden.
 
 {{"demo": "BarLabel.js"}}
 

docs/pages/x/api/charts/bar-chart-pro.json

@@ -14,7 +14,6 @@
         "text": "highlighting docs"
       }
     },
-    "barLabel": { "type": { "name": "union", "description": "'value'<br>&#124;&nbsp;func" } },
     "borderRadius": { "type": { "name": "number" } },
     "brushConfig": {
       "type": {

docs/pages/x/api/charts/bar-chart.json

@@ -14,7 +14,6 @@
         "text": "highlighting docs"
       }
     },
-    "barLabel": { "type": { "name": "union", "description": "'value'<br>&#124;&nbsp;func" } },
     "borderRadius": { "type": { "name": "number" } },
     "brushConfig": {
       "type": {

docs/pages/x/api/charts/bar-plot.json

@@ -39,6 +39,8 @@
     }
   ],
   "classes": [],
+  "spread": true,
+  "themeDefaultProps": null,
   "muiName": "MuiBarPlot",
   "filename": "/packages/x-charts/src/BarChart/BarPlot.tsx",
   "inheritance": null,

docs/pages/x/api/charts/bar-series.json

@@ -7,6 +7,11 @@
   ],
   "properties": {
     "type": { "type": { "description": "'bar'" }, "required": true },
+    "barLabel": {
+      "type": {
+        "description": "'value' | ((item: BarItem, context: BarLabelContext) => string | null | undefined)"
+      }
+    },
     "color": { "type": { "description": "string" } },
     "colorGetter": {
       "type": { "description": "(data: ColorCallbackValue<TValue>) => string" }

docs/translations/api-docs/charts/bar-chart-pro/bar-chart-pro.json

@@ -5,9 +5,6 @@
       "description": "The configuration of axes highlight. Default is set to &#39;band&#39; in the bar direction. Depends on <code>layout</code> prop.",
       "seeMoreText": "See {{link}} for more details."
     },
-    "barLabel": {
-      "description": "If provided, the function will be used to format the label of the bar. It can be set to &#39;value&#39; to display the current value."
-    },
     "borderRadius": { "description": "Defines the border radius of the bar element." },
     "brushConfig": { "description": "Configuration for the brush interaction." },
     "colors": { "description": "Color palette used to colorize multiple series." },

docs/translations/api-docs/charts/bar-chart/bar-chart.json

@@ -5,9 +5,6 @@
       "description": "The configuration of axes highlight. Default is set to &#39;band&#39; in the bar direction. Depends on <code>layout</code> prop.",
       "seeMoreText": "See {{link}} for more details."
     },
-    "barLabel": {
-      "description": "If provided, the function will be used to format the label of the bar. It can be set to &#39;value&#39; to display the current value."
-    },
     "borderRadius": { "description": "Defines the border radius of the bar element." },
     "brushConfig": { "description": "Configuration for the brush interaction." },
     "colors": { "description": "Color palette used to colorize multiple series." },

docs/translations/api-docs/charts/bar-series.json

@@ -2,6 +2,9 @@
   "interfaceDescription": "",
   "propertiesDescriptions": {
     "type": { "description": "" },
+    "barLabel": {
+      "description": "If provided, the function will be used to format the label of the bar.<br />It can be set to &#39;value&#39; to display the current value."
+    },
     "color": {
       "description": "Color to use when displaying the series.<br />If <code>colorGetter</code> is provided, it will be used to get the color for each data point instead.<br />Otherwise, this color will be used for all data points in the series."
     },

packages/x-charts-pro/src/BarChartPro/BarChartPro.tsx

@@ -150,6 +150,7 @@ BarChartPro.propTypes = {
     y: PropTypes.oneOf(['band', 'line', 'none']),
   }),
   /**
+   * @deprecated Use `barLabel` in the chart series instead.
    * If provided, the function will be used to format the label of the bar.
    * It can be set to 'value' to display the current value.
    * @param {BarItem} item The item to format.

packages/x-charts/src/BarChart/BarChart.test.tsx

@@ -43,6 +43,37 @@ describe('<BarChart />', () => {
     expect(screen.getByText('No data to display')).toBeVisible();
   });
 
+  it('prioritizes `barLabel` from series over `barLabel` prop', () => {
+    render(
+      <BarChart
+        barLabel={() => 'Bar label from prop'}
+        series={[{ data: [1], barLabel: () => 'Bar label from series' }]}
+        width={100}
+        height={100}
+        xAxis={[{ data: ['A'] }]}
+        yAxis={[]}
+      />,
+    );
+
+    expect(screen.getByText('Bar label from series')).toBeVisible();
+  });
+
+  it("defaults to `barLabel` prop when `barLabel` from series isn't defined", () => {
+    render(
+      <BarChart
+        barLabel={() => 'Bar label from prop'}
+        series={[{ data: [1] }, { data: [1], barLabel: () => 'Bar label from 2nd series' }]}
+        width={100}
+        height={100}
+        xAxis={[{ data: ['A'] }]}
+        yAxis={[]}
+      />,
+    );
+
+    expect(screen.getByText('Bar label from prop')).toBeVisible();
+    expect(screen.getByText('Bar label from 2nd series')).toBeVisible();
+  });
+
   const wrapper = ({ children }: { children?: React.ReactNode }) => (
     <div style={{ width: 400, height: 400 }}>{children}</div>
   );

packages/x-charts/src/BarChart/BarChart.tsx

@@ -176,6 +176,7 @@ BarChart.propTypes = {
     y: PropTypes.oneOf(['band', 'line', 'none']),
   }),
   /**
+   * @deprecated Use `barLabel` in the chart series instead.
    * If provided, the function will be used to format the label of the bar.
    * It can be set to 'value' to display the current value.
    * @param {BarItem} item The item to format.

packages/x-charts/src/BarChart/BarLabel/BarLabelPlot.tsx

@@ -4,7 +4,7 @@ import { BarLabelItem, BarLabelItemProps } from './BarLabelItem';
 import { useUtilityClasses } from '../barClasses';
 
 type BarLabelPlotProps = {
-  bars: ProcessedBarSeriesData[];
+  processedSeries: ProcessedBarSeriesData;
   skipAnimation?: boolean;
   barLabel?: BarLabelItemProps['barLabel'];
 };
@@ -13,36 +13,38 @@ type BarLabelPlotProps = {
  * @ignore - internal component.
  */
 function BarLabelPlot(props: BarLabelPlotProps) {
-  const { bars, skipAnimation, ...other } = props;
+  const { processedSeries, skipAnimation, ...other } = props;
+  const { seriesId, data } = processedSeries;
   const classes = useUtilityClasses();
 
+  const barLabel = processedSeries.barLabel ?? props.barLabel;
+
+  if (!barLabel) {
+    return null;
+  }
+
   return (
-    <React.Fragment>
-      {bars.flatMap(({ seriesId, data }) => (
-        <g key={seriesId} className={classes.seriesLabels} data-series={seriesId}>
-          {data.map(
-            ({ xOrigin, yOrigin, x, y, dataIndex, color, value, width, height, layout }) => (
-              <BarLabelItem
-                key={dataIndex}
-                seriesId={seriesId}
-                dataIndex={dataIndex}
-                value={value}
-                color={color}
-                xOrigin={xOrigin}
-                yOrigin={yOrigin}
-                x={x}
-                y={y}
-                width={width}
-                height={height}
-                skipAnimation={skipAnimation ?? false}
-                layout={layout ?? 'vertical'}
-                {...other}
-              />
-            ),
-          )}
-        </g>
+    <g key={seriesId} className={classes.seriesLabels} data-series={seriesId}>
+      {data.map(({ xOrigin, yOrigin, x, y, dataIndex, color, value, width, height, layout }) => (
+        <BarLabelItem
+          key={dataIndex}
+          seriesId={seriesId}
+          dataIndex={dataIndex}
+          value={value}
+          color={color}
+          xOrigin={xOrigin}
+          yOrigin={yOrigin}
+          x={x}
+          y={y}
+          width={width}
+          height={height}
+          skipAnimation={skipAnimation ?? false}
+          layout={layout ?? 'vertical'}
+          {...other}
+          barLabel={barLabel}
+        />
       ))}
-    </React.Fragment>
+    </g>
   );
 }
 

packages/x-charts/src/BarChart/BarPlot.test.tsx

@@ -0,0 +1,60 @@
+import { screen, createRenderer } from '@mui/internal-test-utils';
+import * as React from 'react';
+import { ChartContainer } from '../ChartContainer';
+import { BarPlot } from './BarPlot';
+
+describe('BarPlot', () => {
+  const { render } = createRenderer();
+
+  it('`barLabel` prop works', () => {
+    render(
+      <ChartContainer
+        series={[{ type: 'bar', data: [1] }]}
+        width={100}
+        height={100}
+        xAxis={[{ scaleType: 'band', data: ['A'] }]}
+        yAxis={[]}
+      >
+        <BarPlot barLabel={() => 'Bar label from prop'} />
+      </ChartContainer>,
+    );
+
+    expect(screen.getByText('Bar label from prop')).toBeVisible();
+  });
+
+  it('prioritizes `barLabel` from series over `barLabel` prop', () => {
+    render(
+      <ChartContainer
+        series={[{ type: 'bar', data: [1], barLabel: () => 'Bar label from series' }]}
+        width={100}
+        height={100}
+        xAxis={[{ scaleType: 'band', data: ['A'] }]}
+        yAxis={[]}
+      >
+        <BarPlot barLabel={() => 'Bar label from prop'} />
+      </ChartContainer>,
+    );
+
+    expect(screen.getByText('Bar label from series')).toBeVisible();
+  });
+
+  it("defaults to `barLabel` prop when `barLabel` from series isn't defined", () => {
+    render(
+      <ChartContainer
+        series={[
+          { type: 'bar', data: [1] },
+          { type: 'bar', data: [1], barLabel: () => 'Bar label from 2nd series' },
+        ]}
+        width={100}
+        height={100}
+        xAxis={[{ scaleType: 'band', data: ['A'] }]}
+        yAxis={[]}
+      >
+        <BarPlot barLabel={() => 'Bar label from prop'} />
+      </ChartContainer>,
+    );
+
+    expect(screen.getByText('Bar label from prop')).toBeVisible();
+    expect(screen.getByText('Bar label from 2nd series')).toBeVisible();
+  });
+});