Merge remote-tracking branch 'upstream/next' into data-grid/10378

README.md

@@ -32,7 +32,7 @@ Read the Date and Time Pickers [Installation instructions](https://mui.com/x/rea
 
 ### Charts
 
-Read the Charts [Installation instructions](https://mui.com/x/react-charts/#getting-started) in the MUI X docs.
+Read the Charts [Installation instructions](https://mui.com/x/react-charts/getting-started/#installation) in the MUI X docs.
 
 ### Tree View
 

docs/.link-check-errors.txt

@@ -16,4 +16,4 @@ Broken links found by `yarn docs:link-check` that exist:
 - https://mui.com/x/api/data-grid/data-grid/#props
 - https://mui.com/x/api/data-grid/data-grid/#slots
 - https://mui.com/x/api/date-pickers/date-picker/#slots
-- https://mui.com/x/introduction/licensing/#license-key-installation
+- https://mui.com/x/react-charts/#getting-started

docs/data/charts/bars/bars.md

@@ -58,7 +58,7 @@ For more information, see [stacking docs](/x/react-charts/stacking/).
 ## Layout
 
 Bar charts can be rendered with a horizontal layout by providing the `layout="horizontal"` prop.
-If you're using [composition](/x/react-charts/#multiple-charts), you should set the property `layout: 'horizontal'` to each bar series object.
+If you're using [composition](/x/react-charts/composition/), you should set the property `layout: 'horizontal'` to each bar series object.
 
 {{"demo": "HorizontalBars.js"}}
 

docs/data/charts/composition/BasicComposition.js

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import Paper from '@mui/material/Paper';
+import Box from '@mui/material/Box';
+import Checkbox from '@mui/material/Checkbox';
+import FormControlLabel from '@mui/material/FormControlLabel';
+import { ChartContainer } from '@mui/x-charts/ChartContainer';
+import { ResponsiveChartContainer } from '@mui/x-charts/ResponsiveChartContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { LinePlot, MarkPlot } from '@mui/x-charts/LineChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+
+export default function BasicComposition() {
+  const [isResponsive, setIsResponsive] = React.useState(false);
+
+  const Container = isResponsive ? ResponsiveChartContainer : ChartContainer;
+  const sizingProps = isResponsive ? {} : { width: 500, height: 300 };
+  return (
+    <Box sx={{ width: '100%' }}>
+      <FormControlLabel
+        checked={isResponsive}
+        control={
+          <Checkbox onChange={(event) => setIsResponsive(event.target.checked)} />
+        }
+        label="Use responsive container"
+        labelPlacement="end"
+      />
+      <Paper sx={{ width: '100%', height: 300 }} elevation={3}>
+        {/* @ts-ignore */}
+        <Container
+          series={[
+            {
+              type: 'bar',
+              data: [1, 2, 3, 2, 1],
+            },
+            {
+              type: 'line',
+              data: [4, 3, 1, 3, 4],
+            },
+          ]}
+          xAxis={[
+            {
+              data: ['A', 'B', 'C', 'D', 'E'],
+              scaleType: 'band',
+              id: 'x-axis-id',
+            },
+          ]}
+          {...sizingProps}
+        >
+          <BarPlot />
+          <LinePlot />
+          <MarkPlot />
+          <ChartsXAxis label="X axis" position="bottom" axisId="x-axis-id" />
+        </Container>
+      </Paper>
+    </Box>
+  );
+}

docs/data/charts/composition/BasicComposition.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+import Paper from '@mui/material/Paper';
+import Box from '@mui/material/Box';
+import Checkbox from '@mui/material/Checkbox';
+import FormControlLabel from '@mui/material/FormControlLabel';
+import { ChartContainer } from '@mui/x-charts/ChartContainer';
+import { ResponsiveChartContainer } from '@mui/x-charts/ResponsiveChartContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { LinePlot, MarkPlot } from '@mui/x-charts/LineChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+
+export default function BasicComposition() {
+  const [isResponsive, setIsResponsive] = React.useState(false);
+
+  const Container = isResponsive ? ResponsiveChartContainer : ChartContainer;
+  const sizingProps = isResponsive ? {} : { width: 500, height: 300 };
+  return (
+    <Box sx={{ width: '100%' }}>
+      <FormControlLabel
+        checked={isResponsive}
+        control={
+          <Checkbox onChange={(event) => setIsResponsive(event.target.checked)} />
+        }
+        label="Use responsive container"
+        labelPlacement="end"
+      />
+
+      <Paper sx={{ width: '100%', height: 300 }} elevation={3}>
+        {/* @ts-ignore */}
+        <Container
+          series={[
+            {
+              type: 'bar',
+              data: [1, 2, 3, 2, 1],
+            },
+            {
+              type: 'line',
+              data: [4, 3, 1, 3, 4],
+            },
+          ]}
+          xAxis={[
+            {
+              data: ['A', 'B', 'C', 'D', 'E'],
+              scaleType: 'band',
+              id: 'x-axis-id',
+            },
+          ]}
+          {...sizingProps}
+        >
+          <BarPlot />
+          <LinePlot />
+          <MarkPlot />
+          <ChartsXAxis label="X axis" position="bottom" axisId="x-axis-id" />
+        </Container>
+      </Paper>
+    </Box>
+  );
+}

docs/data/charts/composition/SwitchSeriesType.js

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import TextField from '@mui/material/TextField';
+import MenuItem from '@mui/material/MenuItem';
+import { ResponsiveChartContainer } from '@mui/x-charts/ResponsiveChartContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { LinePlot } from '@mui/x-charts/LineChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+
+export default function SwitchSeriesType() {
+  const [type, setType] = React.useState('line');
+
+  return (
+    <Box sx={{ width: '100%' }}>
+      <TextField
+        select
+        value={type}
+        onChange={(event) => setType(event.target.value)}
+        label="series type"
+        sx={{ minWidth: 150 }}
+      >
+        <MenuItem value="line">line</MenuItem>
+        <MenuItem value="bar">bar</MenuItem>
+      </TextField>
+
+      <div>
+        <ResponsiveChartContainer
+          series={[
+            {
+              type,
+              data: [1, 2, 3, 2, 1],
+            },
+            {
+              type,
+              data: [4, 3, 1, 3, 4],
+            },
+          ]}
+          xAxis={[
+            {
+              data: ['A', 'B', 'C', 'D', 'E'],
+              scaleType: 'band',
+              id: 'x-axis-id',
+            },
+          ]}
+          height={200}
+        >
+          <BarPlot />
+          <LinePlot />
+          <ChartsXAxis label="X axis" position="bottom" axisId="x-axis-id" />
+        </ResponsiveChartContainer>
+      </div>
+    </Box>
+  );
+}

docs/data/charts/composition/SwitchSeriesType.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import TextField from '@mui/material/TextField';
+import MenuItem from '@mui/material/MenuItem';
+import { ResponsiveChartContainer } from '@mui/x-charts/ResponsiveChartContainer';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { LinePlot } from '@mui/x-charts/LineChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+
+export default function SwitchSeriesType() {
+  const [type, setType] = React.useState<'line' | 'bar'>('line');
+
+  return (
+    <Box sx={{ width: '100%' }}>
+      <TextField
+        select
+        value={type}
+        onChange={(event) => setType(event.target.value as 'line' | 'bar')}
+        label="series type"
+        sx={{ minWidth: 150 }}
+      >
+        <MenuItem value="line">line</MenuItem>
+        <MenuItem value="bar">bar</MenuItem>
+      </TextField>
+
+      <div>
+        <ResponsiveChartContainer
+          series={[
+            {
+              type,
+              data: [1, 2, 3, 2, 1],
+            },
+            {
+              type,
+              data: [4, 3, 1, 3, 4],
+            },
+          ]}
+          xAxis={[
+            {
+              data: ['A', 'B', 'C', 'D', 'E'],
+              scaleType: 'band',
+              id: 'x-axis-id',
+            },
+          ]}
+          height={200}
+        >
+          <BarPlot />
+          <LinePlot />
+          <ChartsXAxis label="X axis" position="bottom" axisId="x-axis-id" />
+        </ResponsiveChartContainer>
+      </div>
+    </Box>
+  );
+}

docs/data/charts/composition/composition.md

@@ -0,0 +1,143 @@
+---
+title: React Chart composition
+githubLabel: 'component: charts'
+packageName: '@mui/x-charts'
+---
+
+# Chart composition
+
+<p class="description">Creating advanced custom charts.</p>
+
+## Overview
+
+The `@mui/x-charts` follows an architecture based on context providers.
+The overall idea is to pass your series and axes definitions to a single component: the `<ChartContainer />`.
+This component transforms the data and makes it available to its children.
+
+Based on the data provided by the container, you can render some graphical elements with provided subcomponents, such as `<LinePlot />` or `<ChartsYAxis />`.
+Or you can [create your own components](/x/react-charts/components/).
+
+## Container options
+
+### Responsive
+
+There are two types of Chart containers available: `<ChartContainer />` and `<ResponsiveChartContainer />`.
+As the names suggest, the only difference between them is responsiveness.
+
+The first container requires you to provide `width` and `height` props.
+In contrast, `<ResponsiveChartContainer />` automatically adjusts its dimensions to fit the available space defined by the parent element.
+
+:::warning
+The parent element must have intrinsic dimensions.
+If the parent's dimensions rely on its content, the responsive charts will not render.
+:::
+
+The following demo lets you switch between a chart using `<ChartContainer />` with `width` set to `500` and `height` set to `300`, and a chart using `<ResponsiveChartContainer />`, so you can see how they differ.
+
+{{"demo": "BasicComposition.js" }}
+
+### Properties
+
+The chart container gets all props that are not specific to a single graphical element.
+This includes:
+
+- The `xAxis` and `yAxis` props—find more information in the [Axis doc](/x/react-charts/axis/)
+- The `colors` prop as defined in the [color palette page](/x/react-charts/styling/#color-palette)
+- The `series` and `dataset` props
+
+#### Series
+
+The `series` prop is an array of series definitions.
+You can find an explanation about each specific series type in their respective docs page: [Line](/x/react-charts/lines/), [Bar](/x/react-charts/bars/), [Pie](/x/react-charts/pie/), and [Scatter](/x/react-charts/scatter/).
+
+When using a single Charts component, the library can guess which kind of series you are defining.
+For example, the Bar Chart component assumes that `series` will be of type `'bar'`.
+
+With composition, the chart container isn't able to guess the series type, so you must explicitly define it.
+
+```jsx
+<BarChart series={[{
+    data: [1, 2, 3] // No need to specify it is a bar series
+}]} />
+
+<ChartContainer
+  series={[
+    { data: [1, 2, 3], type: 'bar' }, // This series is for the bar chart
+    { data: [3, 2, 1], type: 'line' } // This series is for the line chart
+  ]}
+>
+  <BarPlot /> {/* Will only display series with type: 'bar' */}
+  <LinePlot /> {/* Will only display series with type: 'line' */}
+</ChartContainer>
+```
+
+Those series can use the `dataset` prop the same way that a single-component chart does—see [Using a dataset](/x/react-charts/bars/#using-a-dataset) in the Bar Chart documentation for more details.
+
+In the next demo, the chart is made by composing the `<BarPlot />` and `<LinePlot />` components.
+By modifying the series `type` property, you can switch between rendering a line and a bar.
+
+```jsx
+<ResponsiveChartContainer
+  series={[
+    { type, data: [1, 2, 3, 2, 1] },
+    { type, data: [4, 3, 1, 3, 4] },
+  ]}
+>
+  <BarPlot />
+  <LinePlot />
+  <ChartsXAxis label="X axis" position="bottom" axisId="x-axis-id" />
+</ResponsiveChartContainer>
+```
+
+{{"demo": "SwitchSeriesType.js" }}
+
+## Subcomponents
+
+### Plotting
+
+To display data, you have components named `<XxxPlot />` such as `<LinePlot />`, `<AreaPlot />`, `<MarkPlot />`, `<BarPlot />`, etc.
+
+### Axis
+
+To add axes, you can use `<ChartsXAxis />` and `<ChartsYAxis />` as defined in the [axis page](/x/react-charts/axis/#composition).
+
+It takes an `axisId` prop that indicates which axis, defined in the container, should be rendered.
+If `axisId` is not provided it will pick the first one.
+
+### Additional information
+
+To add a legend to your chart, you can use `<ChartsLegend />`.
+
+Most of the props are explained in the [legend page](/x/react-charts/legend/).
+The demos use the `slotProps.legend` object, but with composition, you can pass props directly to `<ChartsLegend />`.
+
+```jsx
+// With single component chart
+<BarChart
+  slotProps={{
+    legend: {
+      direction: 'row',
+    }
+  }}
+/>
+
+// With composition
+<ChartContainer>
+  <ChartsLegend direction="row" />
+</ChartContainer>
+```
+
+### Interaction
+
+You can also add interactive elements such as `<ChartsAxisHighlight />` and `<ChartsTooltip />`.
+
+:::info
+By default, the container listens to mouse events to keep track of where the mouse is located on the chart.
+
+If you are not using the axis highlight or the tooltip, consider disabling this feature with the `disableAxisListener` prop.
+
+```jsx
+<ChartContainer {...} disableAxisListener>
+```
+
+:::