[docs] Add a performance docs page for charts

Author: alexfauquette

docs/data/charts/bars/bars.md

@@ -275,8 +275,11 @@ When you set `skipAnimation` to `true`, the chart renders without animations.
 
 ## Performance
 
+### SVG batch rendering
+
 By default, each bar is drawn as an SVG `rect` element.
 With many bars, this can slow down rendering.
+
 To render bars more efficiently, you can set the `renderer` prop to `"svg-batch"`.
 This has some trade-offs:
 

docs/data/charts/performance/performance.md

@@ -0,0 +1,116 @@
+---
+title: Charts - Performance
+productId: x-charts
+---
+
+# Charts - Performance
+
+<p class="description">Learn how to keep charts fast and responsive when rendering large datasets.</p>
+
+The performance of a chart can be decomposed in multiple factors: The time for computations, the React re-renders time, the time for the DOM update.
+This page describes the most impactful options you can use to keep rendering smooth.
+
+## Provide stable references
+
+Charts derive a lot of state from their axes/series and recompute it whenever the relevant prop changes by reference.
+Passing a new array or object on every render forces this work to run again and triggers extra re-renders, even when the data itself hasn't changed.
+
+The following props benefit from a stable reference:
+
+- `series`
+- `xAxis`, `yAxis`, and `zAxis`
+- `dataset`
+- `margin`
+- `colors`
+
+When the value never changes, define it outside the component so the same reference is reused across renders:
+
+```jsx
+// Defined once, outside the component.
+const xAxis = [{ scaleType: 'band', data: ['A', 'B', 'C'] }];
+
+function MyChart() {
+  return <BarChart xAxis={xAxis} series={series} height={300} />;
+}
+```
+
+When the value depends on props or state, wrap it in `useMemo` so it is only recomputed when its inputs change:
+
+```jsx
+function MyChart({ data }) {
+  const series = React.useMemo(() => [{ data }], [data]);
+
+  return <LineChart series={series} height={300} />;
+}
+```
+
+:::warning
+The docs uses lot of inlined objects and arrays directly in the JSX (for example `margin={{ top: 10 }}` or `series={[{ data }]}`).
+
+We do that for clarity in the docs sections.
+But each render creates a new reference, which defeats the internal memoization.
+:::
+
+## Skip animations
+
+Animations are convenient for small charts, but they require updating the DOM on every frame.
+With many data points, this work multiplies.
+
+Set the `skipAnimation` prop to render the final state directly, without transitions:
+
+```jsx
+<LineChart series={series} skipAnimation />
+```
+
+:::info
+When `skipAnimation` is unset, charts already respect the user's [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) setting and skip animations for users who opted out of motion.
+:::
+
+## Remove marks from line charts
+
+If you set `showMark` to `true` for line series, a mark element is render for every data point.
+For a series with thousands of points, this adds thousands of DOM nodes that can impact performances.
+
+Either disable marks, or reduce their number
+
+```jsx
+// One mark per 100 values.
+showMark: ({ index }) => index % 100 === 0;
+// Only a mark at the end of the series.
+showMark: 'end';
+// Only a mark at the beginning of the series.
+showMark: 'start';
+```
+
+See [Line charts—Optimization](/x/react-charts/lines/#optimization) for more details.
+
+## Use a more efficient renderer
+
+By default, each item is drawn as its own SVG element—a `<rect>` per bar, a `<circle>` per scatter point.
+This is flexible but doesn't scale well: the number of DOM nodes grows with the number of data points.
+
+Bar and scatter charts accept a `renderer` prop to switch to a more efficient drawing strategy:
+
+- `'svg-single'` (default): renders every item in its own SVG element.
+- `'svg-batch'`: batches all items into a few `<path>` elements, which dramatically reduces the DOM node count for large datasets.
+
+```jsx
+<BarChart series={series} renderer="svg-batch" />
+```
+
+The batch renderer comes with some trade-offs, such as not being able to style individual items with CSS.
+See the dedicated sections for the full list of limitations and live demos:
+
+- [Bar charts—Performance](/x/react-charts/bars/#svg-batch-rendering)
+- [Scatter charts—Performance](/x/react-charts/scatter/#svg-batch-rendering)
+
+### WebGL renderer [<span class="plan-premium"></span>](/x/introduction/licensing/#premium-plan 'Premium plan')
+
+For the largest datasets, `BarChartPremium`, `ScatterChartPremium`, and `HeatmapPremium` support a `'webgl'` renderer that draws items into a single `<canvas>` element, using GPU.
+This trades item-level interactivity for the ability to render hundreds of thousands of points.
+
+```jsx
+<ScatterChartPremium series={series} renderer="webgl" />
+```
+
+See [Bar charts—WebGL renderer](/x/react-charts/bars/#webgl-renderer), [Scatter charts—WebGL renderer](/x/react-charts/scatter/#webgl-renderer), and [Heatmap—WebGL renderer](/x/react-charts/heatmap/#webgl-renderer) for details and demos.

docs/data/pages.ts

@@ -756,6 +756,7 @@ const pages: MuiPage[] = [
               { pathname: '/x/react-charts/label' },
               { pathname: '/x/react-charts/legend' },
               { pathname: '/x/react-charts/localization' },
+              { pathname: '/x/react-charts/performance' },
               { pathname: '/x/react-charts/stacking' },
               { pathname: '/x/react-charts/styling' },
               {

docs/pages/x/react-charts/performance.js

@@ -0,0 +1,6 @@
+import { MarkdownDocs } from '@mui/internal-core-docs/MarkdownDocs';
+import * as pageProps from 'docs/data/charts/performance/performance.md?muiMarkdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}