Merge commit 'e465d2f0938b085385a761139e5d3ac2fa7e50a2' into playwrig…

…ht-1.49
mui · Nov 28, 2024 · 28dc2a3 · 28dc2a3
2 parents f2a7f25 + e465d2f
commit 28dc2a3
Show file tree

Hide file tree

Showing 146 changed files with 2,502 additions and 1,261 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4803,7 +4803,7 @@ Same changes as in `@mui/[email protected]`.
 
   The `useClearableField` hook API has been simplified to now take a `props` parameter instead of a `fieldProps`, `InputProps`, `clearable`, `onClear`, `slots` and `slotProps` parameters.
 
-  You should now be able to directly pass the returned value from your field hook (e.g: `useDateField`) to `useClearableField`
+  You should now be able to directly pass the returned value from your field hook (for example `useDateField`) to `useClearableField`
 
   ```diff
    const fieldResponse = useDateField(props);

diff --git a/docs/data/charts/components/HtmlLegend.js b/docs/data/charts/components/HtmlLegend.js
@@ -0,0 +1,66 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { unstable_useBarSeries } from '@mui/x-charts/hooks';
+import { ChartDataProvider } from '@mui/x-charts/context';
+import { ChartsSurface } from '@mui/x-charts/ChartsSurface';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+import { ChartsYAxis } from '@mui/x-charts/ChartsYAxis';
+
+function MyCustomLegend() {
+  const s = unstable_useBarSeries();
+  return (
+    <table
+      style={{
+        marginLeft: 40,
+        marginRight: 40,
+      }}
+    >
+      <tbody>
+        {Object.values(s?.series ?? []).map((v) => {
+          return (
+            <tr key={v.id}>
+              <td aria-hidden>
+                <div
+                  style={{
+                    background: v.color,
+                    height: 10,
+                    width: 10,
+                    marginRight: 10,
+                    flexShrink: 0,
+                    borderRadius: 5,
+                  }}
+                />
+              </td>
+              <td>{`${v.label}`}</td>
+            </tr>
+          );
+        })}
+      </tbody>
+    </table>
+  );
+}
+
+const veryLongText =
+  "Second Series. You should always try to avoid long sentences. But oftentimes, it's not possible. So, we need to handle them gracefully. This is a very long sentence that should be fully readable.";
+
+export default function HtmlLegend() {
+  return (
+    <Box sx={{ height: 400, display: 'flex', flexDirection: 'column' }}>
+      <ChartDataProvider
+        series={[
+          { label: 'First Series', type: 'bar', data: [100, 200] },
+          { label: veryLongText, type: 'bar', data: [45, 333] },
+        ]}
+        xAxis={[{ data: ['A', 'B'], scaleType: 'band', id: 'x-axis' }]}
+      >
+        <ChartsSurface>
+          <BarPlot />
+          <ChartsXAxis position="bottom" axisId="x-axis" />
+          <ChartsYAxis position="left" />
+        </ChartsSurface>
+        <MyCustomLegend />
+      </ChartDataProvider>
+    </Box>
+  );
+}
diff --git a/docs/data/charts/components/HtmlLegend.tsx b/docs/data/charts/components/HtmlLegend.tsx
@@ -0,0 +1,66 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { unstable_useBarSeries } from '@mui/x-charts/hooks';
+import { ChartDataProvider } from '@mui/x-charts/context';
+import { ChartsSurface } from '@mui/x-charts/ChartsSurface';
+import { BarPlot } from '@mui/x-charts/BarChart';
+import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';
+import { ChartsYAxis } from '@mui/x-charts/ChartsYAxis';
+
+function MyCustomLegend() {
+  const s = unstable_useBarSeries();
+  return (
+    <table
+      style={{
+        marginLeft: 40,
+        marginRight: 40,
+      }}
+    >
+      <tbody>
+        {Object.values(s?.series ?? []).map((v) => {
+          return (
+            <tr key={v.id}>
+              <td aria-hidden>
+                <div
+                  style={{
+                    background: v.color,
+                    height: 10,
+                    width: 10,
+                    marginRight: 10,
+                    flexShrink: 0,
+                    borderRadius: 5,
+                  }}
+                />
+              </td>
+              <td>{`${v.label}`}</td>
+            </tr>
+          );
+        })}
+      </tbody>
+    </table>
+  );
+}
+
+const veryLongText =
+  "Second Series. You should always try to avoid long sentences. But oftentimes, it's not possible. So, we need to handle them gracefully. This is a very long sentence that should be fully readable.";
+
+export default function HtmlLegend() {
+  return (
+    <Box sx={{ height: 400, display: 'flex', flexDirection: 'column' }}>
+      <ChartDataProvider
+        series={[
+          { label: 'First Series', type: 'bar', data: [100, 200] },
+          { label: veryLongText, type: 'bar', data: [45, 333] },
+        ]}
+        xAxis={[{ data: ['A', 'B'], scaleType: 'band', id: 'x-axis' }]}
+      >
+        <ChartsSurface>
+          <BarPlot />
+          <ChartsXAxis position="bottom" axisId="x-axis" />
+          <ChartsYAxis position="left" />
+        </ChartsSurface>
+        <MyCustomLegend />
+      </ChartDataProvider>
+    </Box>
+  );
+}
diff --git a/docs/data/charts/components/HtmlLegend.tsx.preview b/docs/data/charts/components/HtmlLegend.tsx.preview
@@ -0,0 +1,14 @@
+<ChartDataProvider
+  series={[
+    { label: 'First Series', type: 'bar', data: [100, 200] },
+    { label: veryLongText, type: 'bar', data: [45, 333] },
+  ]}
+  xAxis={[{ data: ['A', 'B'], scaleType: 'band', id: 'x-axis' }]}
+>
+  <ChartsSurface>
+    <BarPlot />
+    <ChartsXAxis position="bottom" axisId="x-axis" />
+    <ChartsYAxis position="left" />
+  </ChartsSurface>
+  <MyCustomLegend />
+</ChartDataProvider>
diff --git a/docs/data/charts/components/components.md b/docs/data/charts/components/components.md
@@ -76,3 +76,22 @@ By using `invert`, the value associated with the current mouse coordinate `y` ca
 ```
 
 {{"demo": "ScaleDemo.js"}}
+
+## HTML components
+
+With the introduction of the `ChartDataProvider` in v8, the chart data can be accessed from any component.
+This allows you to create HTML components that interact with the charts data.
+
+In the next example, notice that `MyCustomLegend` component displays the series names and colors.
+This creates an html `table` element, which handles long series names better than the default legend.
+
+{{"demo": "HtmlLegend.js"}}
+
+:::warning
+Note that the HTML components are not part of the SVG hierarchy.
+Hence, they should be:
+
+- Outside the `<ChartsSurface />` component to avoid mixing HTAM and SVG.
+- Inside the `<ChartDataProvider />` component to get access to the data.
+
+:::
diff --git a/docs/data/charts/composition/composition.md b/docs/data/charts/composition/composition.md
@@ -2,7 +2,7 @@
 title: React Chart composition
 productId: x-charts
 githubLabel: 'component: charts'
-components: ChartContainer, ChartContainerPro, ChartsGrid
+components: ChartContainer, ChartContainerPro, ChartsGrid, ChartDataProvider, ChartsSurface
 packageName: '@mui/x-charts'
 ---
 
@@ -13,11 +13,75 @@ packageName: '@mui/x-charts'
 ## 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.
+The overall idea is to pass your series and axes definitions to special components.
+This component transforms the data and makes it available to its children, which can be composed.
 
-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/).
+There are two main classes of components, which are used to create a chart.
+
+### Structural components
+
+These are used to define the chart's structure and data.
+
+#### The Data Provider and Surface components
+
+As the name suggests, the `ChartDataProvider` provides the data to the children components.
+While the `ChartsSurface` renders the SVG elements.
+
+```jsx
+<ChartDataProvider
+  // The configuration of the chart
+  series={[{ type: 'bar', data: [100, 200] }]}
+  xAxis={[{ scaleType: 'band', data: ['A', 'B'] }]}
+  width={500}
+  height={300}
+>
+  <ChartsSurface
+    // Ref needs to be directly on the ChartsSurface
+    ref={mySvgRef}
+  >
+    {children}
+  </ChartsSurface>
+</ChartDataProvider>
+```
+
+:::info
+The demos here are using the `ChartContainer` component.
+To see demos using the separate `ChartDataProvider` and `ChartsSurface` components, check the [HTML components documentation](/x/react-charts/components/#html-components).
+:::
+
+#### The `ChartContainer` helper
+
+This component is a composition of the two previous components.
+It can be used instead of them when there is no need to customize anything outside the chart's graphical elements.
+
+```jsx
+<ChartContainer
+  // The configuration of the chart
+  series={[{ type: 'bar', data: [100, 200] }]}
+  xAxis={[{ scaleType: 'band', data: ['A', 'B'] }]}
+  width={500}
+  height={300}
+  // Ref is forwarded internally to the ChartsSurface
+  ref={mySvgRef}
+>
+  {children}
+</ChartContainer>
+```
+
+### Graphical components
+
+These are any component that render the graphical elements of the chart.
+They are the children of the **Structural components** shown above.
+There are many of them, so they won't all be listed here.
+You can even [create your own components](/x/react-charts/components/).
+
+Some examples of graphical components are:
+
+- `LinePlot`
+- `BarPlot`
+- `ChartsXAxis`
+- `ChartsLegend`
+- `ChartsTooltip`
 
 ## Container options
 

diff --git a/docs/data/charts/heatmap/heatmap.md b/docs/data/charts/heatmap/heatmap.md
@@ -1,7 +1,7 @@
 ---
 title: React Heatmap chart
 productId: x-charts
-components: Heatmap, HeatmapPlot, DefaultHeatmapTooltip
+components: Heatmap, HeatmapPlot, HeatmapTooltip
 ---
 
 # Charts - Heatmap [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan 'Pro plan')