From 0b7d3866ec620882e518160402f61e268e3d3b71 Mon Sep 17 00:00:00 2001
From: Jose C Quintas Jr <juniorquintas@gmail.com>
Date: Mon, 8 Apr 2024 15:00:16 +0200
Subject: [PATCH] [docs] Add AxisFormatter documentation for customizing
 tick/tooltip value formatting (#12700)

Signed-off-by: Jose C Quintas Jr <juniorquintas@gmail.com>
Co-authored-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com>
---
 docs/data/charts/tooltip/AxisFormatter.js     | 74 +++++++++++++++++++
 docs/data/charts/tooltip/AxisFormatter.tsx    | 74 +++++++++++++++++++
 .../charts/tooltip/AxisFormatter.tsx.preview  | 13 ++++
 docs/data/charts/tooltip/tooltip.md           | 13 ++++
 4 files changed, 174 insertions(+)
 create mode 100644 docs/data/charts/tooltip/AxisFormatter.js
 create mode 100644 docs/data/charts/tooltip/AxisFormatter.tsx
 create mode 100644 docs/data/charts/tooltip/AxisFormatter.tsx.preview

diff --git a/docs/data/charts/tooltip/AxisFormatter.js b/docs/data/charts/tooltip/AxisFormatter.js
new file mode 100644
index 000000000000..07f82faf0cb8
--- /dev/null
+++ b/docs/data/charts/tooltip/AxisFormatter.js
@@ -0,0 +1,74 @@
+import * as React from 'react';
+import { BarChart } from '@mui/x-charts/BarChart';
+import { axisClasses } from '@mui/x-charts';
+
+const dataset = [
+  { name: 'Austria', code: 'AT', gdp: 471 },
+  { name: 'Belgium', code: 'BE', gdp: 583 },
+  { name: 'Bulgaria', code: 'BG', gdp: 90.35 },
+  { name: 'Croatia', code: 'HR', gdp: 71.6 },
+  { name: 'Czech Republic', code: 'CZ', gdp: 291 },
+  { name: 'Denmark', code: 'DK', gdp: 400 },
+  { name: 'Finland', code: 'FI', gdp: 283 },
+  { name: 'France', code: 'FR', gdp: 2779 },
+  { name: 'Germany', code: 'DE', gdp: 4082 },
+  { name: 'Greece', code: 'GR', gdp: 218 },
+  { name: 'Hungary', code: 'HU', gdp: 177 },
+  { name: 'Ireland', code: 'IE', gdp: 533 },
+  { name: 'Italy', code: 'IT', gdp: 2050 },
+  { name: 'Netherlands', code: 'NL', gdp: 1009 },
+  { name: 'Poland', code: 'PL', gdp: 688 },
+  { name: 'Portugal', code: 'PT', gdp: 255 },
+  { name: 'Romania', code: 'RO', gdp: 301 },
+  { name: 'Slovakia', code: 'SK', gdp: 115 },
+  { name: 'Spain', code: 'ES', gdp: 1418 },
+  { name: 'Sweden', code: 'SE', gdp: 591 },
+];
+
+const chartParams = {
+  yAxis: [
+    {
+      label: 'GDP (million $USD)',
+    },
+  ],
+  series: [
+    {
+      label: 'GDP',
+      dataKey: 'gdp',
+      valueFormatter: (v) =>
+        new Intl.NumberFormat('en-US', {
+          style: 'currency',
+          currency: 'USD',
+          compactDisplay: 'short',
+          notation: 'compact',
+        }).format((v || 0) * 1_000_000),
+    },
+  ],
+  slotProps: { legend: { hidden: true } },
+  dataset,
+  width: 600,
+  height: 400,
+  sx: {
+    [`.${axisClasses.left} .${axisClasses.label}`]: {
+      transform: 'translate(-20px, 0)',
+    },
+  },
+};
+
+export default function AxisFormatter() {
+  return (
+    <BarChart
+      xAxis={[
+        {
+          scaleType: 'band',
+          dataKey: 'code',
+          valueFormatter: (code, context) =>
+            context.location === 'tick'
+              ? code
+              : `Country: ${dataset.find((d) => d.code === code)?.name} (${code})`,
+        },
+      ]}
+      {...chartParams}
+    />
+  );
+}
diff --git a/docs/data/charts/tooltip/AxisFormatter.tsx b/docs/data/charts/tooltip/AxisFormatter.tsx
new file mode 100644
index 000000000000..5ba4b86b170e
--- /dev/null
+++ b/docs/data/charts/tooltip/AxisFormatter.tsx
@@ -0,0 +1,74 @@
+import * as React from 'react';
+import { BarChart, BarChartProps } from '@mui/x-charts/BarChart';
+import { axisClasses } from '@mui/x-charts';
+
+const dataset = [
+  { name: 'Austria', code: 'AT', gdp: 471 },
+  { name: 'Belgium', code: 'BE', gdp: 583 },
+  { name: 'Bulgaria', code: 'BG', gdp: 90.35 },
+  { name: 'Croatia', code: 'HR', gdp: 71.6 },
+  { name: 'Czech Republic', code: 'CZ', gdp: 291 },
+  { name: 'Denmark', code: 'DK', gdp: 400 },
+  { name: 'Finland', code: 'FI', gdp: 283 },
+  { name: 'France', code: 'FR', gdp: 2779 },
+  { name: 'Germany', code: 'DE', gdp: 4082 },
+  { name: 'Greece', code: 'GR', gdp: 218 },
+  { name: 'Hungary', code: 'HU', gdp: 177 },
+  { name: 'Ireland', code: 'IE', gdp: 533 },
+  { name: 'Italy', code: 'IT', gdp: 2050 },
+  { name: 'Netherlands', code: 'NL', gdp: 1009 },
+  { name: 'Poland', code: 'PL', gdp: 688 },
+  { name: 'Portugal', code: 'PT', gdp: 255 },
+  { name: 'Romania', code: 'RO', gdp: 301 },
+  { name: 'Slovakia', code: 'SK', gdp: 115 },
+  { name: 'Spain', code: 'ES', gdp: 1418 },
+  { name: 'Sweden', code: 'SE', gdp: 591 },
+];
+
+const chartParams: BarChartProps = {
+  yAxis: [
+    {
+      label: 'GDP (million $USD)',
+    },
+  ],
+  series: [
+    {
+      label: 'GDP',
+      dataKey: 'gdp',
+      valueFormatter: (v) =>
+        new Intl.NumberFormat('en-US', {
+          style: 'currency',
+          currency: 'USD',
+          compactDisplay: 'short',
+          notation: 'compact',
+        }).format((v || 0) * 1_000_000),
+    },
+  ],
+  slotProps: { legend: { hidden: true } },
+  dataset,
+  width: 600,
+  height: 400,
+  sx: {
+    [`.${axisClasses.left} .${axisClasses.label}`]: {
+      transform: 'translate(-20px, 0)',
+    },
+  },
+};
+
+export default function AxisFormatter() {
+  return (
+    <BarChart
+      xAxis={[
+        {
+          scaleType: 'band',
+          dataKey: 'code',
+          valueFormatter: (code, context) =>
+            context.location === 'tick'
+              ? code
+              : `Country: ${dataset.find((d) => d.code === code)?.name} (${code})`,
+        },
+      ]}
+      {...chartParams}
+    />
+  );
+}
diff --git a/docs/data/charts/tooltip/AxisFormatter.tsx.preview b/docs/data/charts/tooltip/AxisFormatter.tsx.preview
new file mode 100644
index 000000000000..c12fab7e6707
--- /dev/null
+++ b/docs/data/charts/tooltip/AxisFormatter.tsx.preview
@@ -0,0 +1,13 @@
+<BarChart
+  xAxis={[
+    {
+      scaleType: 'band',
+      dataKey: 'code',
+      valueFormatter: (code, context) =>
+        context.location === 'tick'
+          ? code
+          : `Country: ${dataset.find((d) => d.code === code)?.name} (${code})`,
+    },
+  ]}
+  {...chartParams}
+/>
\ No newline at end of file
diff --git a/docs/data/charts/tooltip/tooltip.md b/docs/data/charts/tooltip/tooltip.md
index 0c94979395de..a3c463c96dcf 100644
--- a/docs/data/charts/tooltip/tooltip.md
+++ b/docs/data/charts/tooltip/tooltip.md
@@ -69,6 +69,19 @@ Here is a demo with:
 
 {{"demo": "Formatting.js"}}
 
+### Axis formatter
+
+To modify how data is displayed in the axis use the `valueFormatter` property.
+
+Its second argument is a context that provides a `location` property with either `'tick'` or `'tooltip'`.
+
+In this demo, you can see:
+
+- The country axis displays only the country code
+- The label displays annotated data `Country: name (code)`
+
+{{"demo": "AxisFormatter.js"}}
+
 ### Hiding values
 
 You can hide the axis value with `hideTooltip` in the `xAxis` props.