[charts] Add an overlay for "no data" or "loading" states (mui#12817)

DungTiger · Jul 23, 2024 · bdd885b · bdd885b
1 parent dffcd41
commit bdd885b
Show file tree

Hide file tree

Showing 40 changed files with 600 additions and 27 deletions.
diff --git a/docs/data/charts/styling/CustomOverlay.js b/docs/data/charts/styling/CustomOverlay.js
@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import Stack from '@mui/material/Stack';
+import { BarChart } from '@mui/x-charts/BarChart';
+import { useDrawingArea, useXScale, useYScale } from '@mui/x-charts/hooks';
+
+const ratios = [0.2, 0.8, 0.6, 0.5];
+
+const LoadingReact = styled('rect')({
+  opacity: 0.2,
+  fill: 'lightgray',
+});
+
+const LoadingText = styled('text')(({ theme }) => ({
+  stroke: 'none',
+  fill: theme.palette.text.primary,
+  shapeRendering: 'crispEdges',
+  textAnchor: 'middle',
+  dominantBaseline: 'middle',
+}));
+
+function LoadingOverlay() {
+  const xScale = useXScale();
+  const yScale = useYScale();
+  const { left, width, height } = useDrawingArea();
+
+  const bandWidth = xScale.bandwidth();
+
+  const [bottom, top] = yScale.range();
+
+  return (
+    <g>
+      {xScale.domain().map((item, index) => {
+        const ratio = ratios[index % ratios.length];
+        const barHeight = ratio * (bottom - top);
+
+        return (
+          <LoadingReact
+            x={xScale(item)}
+            width={bandWidth}
+            y={bottom - barHeight}
+            height={height}
+          />
+        );
+      })}
+      <LoadingText x={left + width / 2} y={top + height / 2}>
+        Loading data ...
+      </LoadingText>
+    </g>
+  );
+}
+
+export default function CustomOverlay() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <BarChart
+        slotProps={{
+          noDataOverlay: { message: 'No data to display in this chart' },
+        }}
+        series={[]}
+        margin={{ top: 10, right: 10, left: 25, bottom: 25 }}
+        height={150}
+      />
+      <BarChart
+        loading
+        xAxis={[
+          { scaleType: 'band', data: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'] },
+        ]}
+        slots={{ loadingOverlay: LoadingOverlay }}
+        series={[]}
+        margin={{ top: 10, right: 10, left: 25, bottom: 25 }}
+        height={150}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/CustomOverlay.tsx b/docs/data/charts/styling/CustomOverlay.tsx
@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import Stack from '@mui/material/Stack';
+import { BarChart } from '@mui/x-charts/BarChart';
+import { useDrawingArea, useXScale, useYScale } from '@mui/x-charts/hooks';
+
+const ratios = [0.2, 0.8, 0.6, 0.5];
+
+const LoadingReact = styled('rect')({
+  opacity: 0.2,
+  fill: 'lightgray',
+});
+
+const LoadingText = styled('text')(({ theme }) => ({
+  stroke: 'none',
+  fill: theme.palette.text.primary,
+  shapeRendering: 'crispEdges',
+  textAnchor: 'middle',
+  dominantBaseline: 'middle',
+}));
+
+function LoadingOverlay() {
+  const xScale = useXScale<'band'>();
+  const yScale = useYScale();
+  const { left, width, height } = useDrawingArea();
+
+  const bandWidth = xScale.bandwidth();
+
+  const [bottom, top] = yScale.range();
+
+  return (
+    <g>
+      {xScale.domain().map((item, index) => {
+        const ratio = ratios[index % ratios.length];
+        const barHeight = ratio * (bottom - top);
+
+        return (
+          <LoadingReact
+            x={xScale(item)}
+            width={bandWidth}
+            y={bottom - barHeight}
+            height={height}
+          />
+        );
+      })}
+      <LoadingText x={left + width / 2} y={top + height / 2}>
+        Loading data ...
+      </LoadingText>
+    </g>
+  );
+}
+
+export default function CustomOverlay() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <BarChart
+        slotProps={{
+          noDataOverlay: { message: 'No data to display in this chart' },
+        }}
+        series={[]}
+        margin={{ top: 10, right: 10, left: 25, bottom: 25 }}
+        height={150}
+      />
+      <BarChart
+        loading
+        xAxis={[
+          { scaleType: 'band', data: ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'] },
+        ]}
+        slots={{ loadingOverlay: LoadingOverlay }}
+        series={[]}
+        margin={{ top: 10, right: 10, left: 25, bottom: 25 }}
+        height={150}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/Overlay.js b/docs/data/charts/styling/Overlay.js
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+const emptySeries = {
+  series: [],
+  margin: { top: 10, right: 10, left: 25, bottom: 25 },
+  height: 150,
+};
+
+export default function Overlay() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <LineChart loading {...emptySeries} />
+      <LineChart {...emptySeries} />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/Overlay.tsx b/docs/data/charts/styling/Overlay.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+const emptySeries = {
+  series: [],
+  margin: { top: 10, right: 10, left: 25, bottom: 25 },
+  height: 150,
+};
+
+export default function Overlay() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <LineChart loading {...emptySeries} />
+      <LineChart {...emptySeries} />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/Overlay.tsx.preview b/docs/data/charts/styling/Overlay.tsx.preview
@@ -0,0 +1,2 @@
+<LineChart loading {...emptySeries} />
+<LineChart {...emptySeries} />
diff --git a/docs/data/charts/styling/OverlayWithAxis.js b/docs/data/charts/styling/OverlayWithAxis.js
@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+const emptySeries = {
+  series: [],
+  margin: { top: 10, right: 10, left: 25, bottom: 25 },
+  height: 150,
+};
+
+export default function OverlayWithAxis() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <LineChart
+        loading
+        xAxis={[{ data: [0, 1, 2, 4, 5] }]}
+        yAxis={[{ min: 0, max: 10 }]}
+        {...emptySeries}
+      />
+      <LineChart
+        yAxis={[{ min: -5, max: 5 }]}
+        xAxis={[
+          {
+            scaleType: 'time',
+            data: [
+              new Date(2019, 0, 1),
+              new Date(2020, 0, 1),
+              new Date(2021, 0, 1),
+              new Date(2022, 0, 1),
+            ],
+            tickNumber: 3,
+          },
+        ]}
+        {...emptySeries}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/OverlayWithAxis.tsx b/docs/data/charts/styling/OverlayWithAxis.tsx
@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Stack from '@mui/material/Stack';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+const emptySeries = {
+  series: [],
+  margin: { top: 10, right: 10, left: 25, bottom: 25 },
+  height: 150,
+};
+
+export default function OverlayWithAxis() {
+  return (
+    <Stack direction={{ md: 'row', xs: 'column' }} sx={{ width: '100%' }}>
+      <LineChart
+        loading
+        xAxis={[{ data: [0, 1, 2, 4, 5] }]}
+        yAxis={[{ min: 0, max: 10 }]}
+        {...emptySeries}
+      />
+      <LineChart
+        yAxis={[{ min: -5, max: 5 }]}
+        xAxis={[
+          {
+            scaleType: 'time',
+            data: [
+              new Date(2019, 0, 1),
+              new Date(2020, 0, 1),
+              new Date(2021, 0, 1),
+              new Date(2022, 0, 1),
+            ],
+            tickNumber: 3,
+          },
+        ]}
+        {...emptySeries}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/charts/styling/styling.md b/docs/data/charts/styling/styling.md
@@ -102,6 +102,40 @@ This configuration can be used in Bar Charts to set colors according to string c
 }
 ```
 
+## Overlay
+
+Charts have a _loading_ and _noData_ overlays that appears if
+
+- `loading` prop is set to `true`.
+- There is no data to display.
+
+{{"demo": "Overlay.js"}}
+
+### Axis display
+
+You can provide the axes data in order to display them while loading the data.
+
+{{"demo": "OverlayWithAxis.js"}}
+
+### Custom overlay
+
+To modify the overly message, you can use the `message` props as follow.
+
+```jsx
+<BarChart
+  slotProps={{
+    // Custom loading message
+    loadingOverlay: { message: 'Data should be available soon.' },
+    // Custom message for empty chart
+    noDataOverlay: { message: 'Select some data to display.' },
+  }}
+/>
+```
+
+For more advanced customization, use the `loadingOverlay` and `noDataOverlay` slots link in the following demo.
+
+{{"demo": "CustomOverlay.js"}}
+
 ## Styling
 
 ### Size

diff --git a/docs/pages/x/api/charts/bar-chart.json b/docs/pages/x/api/charts/bar-chart.json
@@ -36,6 +36,7 @@
       "type": { "name": "union", "description": "object<br>&#124;&nbsp;string" },
       "default": "yAxisIds[0] The id of the first provided axis"
     },
+    "loading": { "type": { "name": "bool" } },
     "margin": {
       "type": {
         "name": "shape",
@@ -152,6 +153,18 @@
       "description": "Custom component for displaying tooltip content when triggered by item event.",
       "default": "DefaultChartsItemTooltipContent",
       "class": null
+    },
+    {
+      "name": "loadingOverlay",
+      "description": "Overlay component rendered when the chart is in a loading state.",
+      "default": "ChartsLoadingOverlay",
+      "class": null
+    },
+    {
+      "name": "noDataOverlay",
+      "description": "Overlay component rendered when the chart has no data to display.",
+      "default": "ChartsNoDataOverlay",
+      "class": null
     }
   ],
   "classes": [],

diff --git a/docs/pages/x/api/charts/default-charts-axis-tooltip-content.json b/docs/pages/x/api/charts/default-charts-axis-tooltip-content.json
@@ -8,7 +8,6 @@
       },
       "required": true
     },
-    "axisValue": { "type": { "name": "any" }, "required": true },
     "classes": {
       "type": { "name": "object" },
       "required": true,
@@ -18,6 +17,9 @@
       "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" },
       "required": true
     },
+    "axisValue": {
+      "type": { "name": "union", "description": "Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string" }
+    },
     "dataIndex": { "type": { "name": "number" } }
   },
   "name": "DefaultChartsAxisTooltipContent",

diff --git a/docs/pages/x/api/charts/line-chart.json b/docs/pages/x/api/charts/line-chart.json
@@ -34,6 +34,7 @@
       "type": { "name": "union", "description": "object<br>&#124;&nbsp;string" },
       "default": "yAxisIds[0] The id of the first provided axis"
     },
+    "loading": { "type": { "name": "bool" } },
     "margin": {
       "type": {
         "name": "shape",
@@ -155,6 +156,18 @@
       "description": "Custom component for displaying tooltip content when triggered by item event.",
       "default": "DefaultChartsItemTooltipContent",
       "class": null
+    },
+    {
+      "name": "loadingOverlay",
+      "description": "Overlay component rendered when the chart is in a loading state.",
+      "default": "ChartsLoadingOverlay",
+      "class": null
+    },
+    {
+      "name": "noDataOverlay",
+      "description": "Overlay component rendered when the chart has no data to display.",
+      "default": "ChartsNoDataOverlay",
+      "class": null
     }
   ],
   "classes": [],
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		<LineChart loading {...emptySeries} />
		<LineChart {...emptySeries} />