[charts] Use plugin system for series and axes (mui#15865)

Co-authored-by: Jose C Quintas Jr <juniorquintas@gmail.com>
lauri865 · Jan 10, 2025 · 1fdcf85 · 1fdcf85
1 parent 5999d29
commit 1fdcf85
Show file tree

Hide file tree

Showing 222 changed files with 3,489 additions and 3,303 deletions.
diff --git a/docs/data/charts/zoom-and-pan/ZoomControlled.js b/docs/data/charts/zoom-and-pan/ZoomControlled.js
@@ -1,24 +1,28 @@
 import * as React from 'react';
 import { LineChartPro } from '@mui/x-charts-pro/LineChartPro';
-
 import Button from '@mui/material/Button';
 import Stack from '@mui/material/Stack';
 
+const initialZoomData = [
+  {
+    axisId: 'my-x-axis',
+    start: 20,
+    end: 40,
+  },
+];
+
 export default function ZoomControlled() {
-  const [zoom, setZoom] = React.useState([
-    {
-      axisId: 'my-x-axis',
-      start: 20,
-      end: 40,
-    },
-  ]);
+  const apiRef = React.useRef(undefined);
+
+  const [zoomData, setZoomData] = React.useState(initialZoomData);
 
   return (
     <Stack direction={'column'} alignItems={'center'}>
       <LineChartPro
         {...chartProps}
-        zoom={zoom}
-        onZoomChange={setZoom}
+        initialZoom={initialZoomData}
+        apiRef={apiRef}
+        onZoomChange={(newZoomData) => setZoomData(newZoomData)}
         xAxis={[
           {
             zoom: true,
@@ -28,9 +32,12 @@ export default function ZoomControlled() {
           },
         ]}
       />
+      <pre>{JSON.stringify(zoomData, null, 2)}</pre>
       <Button
         variant="contained"
-        onClick={() => setZoom([{ axisId: 'my-x-axis', start: 0, end: 100 }])}
+        onClick={() =>
+          apiRef.current.setZoomData([{ axisId: 'my-x-axis', start: 0, end: 100 }])
+        }
       >
         Reset zoom
       </Button>

diff --git a/docs/data/charts/zoom-and-pan/ZoomControlled.tsx b/docs/data/charts/zoom-and-pan/ZoomControlled.tsx
@@ -1,24 +1,29 @@
 import * as React from 'react';
 import { LineChartPro } from '@mui/x-charts-pro/LineChartPro';
-import { ZoomData } from '@mui/x-charts-pro/context';
 import Button from '@mui/material/Button';
 import Stack from '@mui/material/Stack';
+import { ChartPublicAPI, ZoomData } from '@mui/x-charts/internals';
 
+const initialZoomData: ZoomData[] = [
+  {
+    axisId: 'my-x-axis',
+    start: 20,
+    end: 40,
+  },
+];
 export default function ZoomControlled() {
-  const [zoom, setZoom] = React.useState<ZoomData[]>([
-    {
-      axisId: 'my-x-axis',
-      start: 20,
-      end: 40,
-    },
-  ]);
+  const apiRef = React.useRef(undefined) as React.MutableRefObject<
+    ChartPublicAPI<[any]> | undefined
+  >;
+  const [zoomData, setZoomData] = React.useState(initialZoomData);
 
   return (
     <Stack direction={'column'} alignItems={'center'}>
       <LineChartPro
         {...chartProps}
-        zoom={zoom}
-        onZoomChange={setZoom}
+        initialZoom={initialZoomData}
+        apiRef={apiRef}
+        onZoomChange={(newZoomData) => setZoomData(newZoomData)}
         xAxis={[
           {
             zoom: true,
@@ -28,9 +33,12 @@ export default function ZoomControlled() {
           },
         ]}
       />
+      <pre>{JSON.stringify(zoomData, null, 2)}</pre>
       <Button
         variant="contained"
-        onClick={() => setZoom([{ axisId: 'my-x-axis', start: 0, end: 100 }])}
+        onClick={() =>
+          apiRef.current.setZoomData([{ axisId: 'my-x-axis', start: 0, end: 100 }])
+        }
       >
         Reset zoom
       </Button>

diff --git a/docs/data/charts/zoom-and-pan/zoom-and-pan.md b/docs/data/charts/zoom-and-pan/zoom-and-pan.md
@@ -41,21 +41,6 @@ The following options are available:
 
 {{"demo": "ZoomOptionsNoSnap.js", "hideToolbar": true, "bg": "playground"}}
 
-## Controlled zoom
-
-You can control the zoom state by setting the `zoom` and `onZoomChange` props.
-This way, you can control the zoom state from outside the chart.
-
-The `onZoomChange` prop is a function that receives the new zoom state.
-
-While the `zoom` prop is an array of objects that define the zoom state for each axis with zoom enabled.
-
-- **axisId**: The id of the axis to control.
-- **start**: The starting percentage of the axis range.
-- **end**: The ending percentage of the zoom range.
-
-{{"demo": "ZoomControlled.js"}}
-
 ## Zoom filtering
 
 You can make the zoom of an axis affect one or more axes extremums by setting the `zoom.filterMode` prop on the axis config.
@@ -66,3 +51,20 @@ You can make the zoom of an axis affect one or more axes extremums by setting th
 See how the secondary axis adapts to the visible part of the primary axis in the following example.
 
 {{"demo": "ZoomFilterMode.js"}}
+
+## External zoom management
+
+You can manage the zoom state by two means:
+
+- By defining an initial state with the `initialZoom` prop.
+- By imperatively set a zoom value with the `setZoomData` method of the public api.
+
+In addition, the `onZoomChange` prop is a function that receives the new zoom state.
+
+The `zoom` state is an array of objects that define the zoom state for each axis with zoom enabled.
+
+- **axisId**: The id of the axis to control.
+- **start**: The starting percentage of the axis range.
+- **end**: The ending percentage of the zoom range.
+
+{{"demo": "ZoomControlled.js"}}
diff --git a/docs/pages/x/api/charts/bar-chart-pro.json b/docs/pages/x/api/charts/bar-chart-pro.json
@@ -37,6 +37,13 @@
         "description": "{ dataIndex?: number, seriesId?: number<br>&#124;&nbsp;string }"
       }
     },
+    "id": { "type": { "name": "string" } },
+    "initialZoom": {
+      "type": {
+        "name": "arrayOf",
+        "description": "Array&lt;{ axisId: number<br>&#124;&nbsp;string, end: number, start: number }&gt;"
+      }
+    },
     "layout": {
       "type": { "name": "enum", "description": "'horizontal'<br>&#124;&nbsp;'vertical'" },
       "default": "'vertical'"
@@ -50,8 +57,7 @@
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "onAxisClick": {
       "type": { "name": "func" },
@@ -109,10 +115,10 @@
         "description": "Array&lt;{ classes?: object, colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, disableLine?: bool, disableTicks?: bool, domainLimit?: 'nice'<br>&#124;&nbsp;'strict'<br>&#124;&nbsp;func, fill?: string, hideTooltip?: bool, id?: number<br>&#124;&nbsp;string, label?: string, labelStyle?: object, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, position?: 'left'<br>&#124;&nbsp;'right', reverse?: bool, scaleType?: 'band'<br>&#124;&nbsp;'linear'<br>&#124;&nbsp;'log'<br>&#124;&nbsp;'point'<br>&#124;&nbsp;'pow'<br>&#124;&nbsp;'sqrt'<br>&#124;&nbsp;'time'<br>&#124;&nbsp;'utc', slotProps?: object, slots?: object, stroke?: string, sx?: Array&lt;func<br>&#124;&nbsp;object<br>&#124;&nbsp;bool&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object, tickInterval?: 'auto'<br>&#124;&nbsp;array<br>&#124;&nbsp;func, tickLabelInterval?: 'auto'<br>&#124;&nbsp;func, tickLabelPlacement?: 'middle'<br>&#124;&nbsp;'tick', tickLabelStyle?: object, tickMaxStep?: number, tickMinStep?: number, tickNumber?: number, tickPlacement?: 'end'<br>&#124;&nbsp;'extremities'<br>&#124;&nbsp;'middle'<br>&#124;&nbsp;'start', tickSize?: number, valueFormatter?: func, zoom?: { filterMode?: 'discard'<br>&#124;&nbsp;'keep', maxEnd?: number, maxSpan?: number, minSpan?: number, minStart?: number, panning?: bool, step?: number }<br>&#124;&nbsp;bool }&gt;"
       }
     },
-    "zoom": {
+    "zAxis": {
       "type": {
         "name": "arrayOf",
-        "description": "Array&lt;{ axisId: number<br>&#124;&nbsp;string, end: number, start: number }&gt;"
+        "description": "Array&lt;{ colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, id?: string, max?: number, min?: number }&gt;"
       }
     }
   },

diff --git a/docs/pages/x/api/charts/bar-chart.json b/docs/pages/x/api/charts/bar-chart.json
@@ -37,6 +37,7 @@
         "description": "{ dataIndex?: number, seriesId?: number<br>&#124;&nbsp;string }"
       }
     },
+    "id": { "type": { "name": "string" } },
     "layout": {
       "type": { "name": "enum", "description": "'horizontal'<br>&#124;&nbsp;'vertical'" },
       "default": "'vertical'"
@@ -50,8 +51,7 @@
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "onAxisClick": {
       "type": { "name": "func" },

diff --git a/docs/pages/x/api/charts/chart-container-pro.json b/docs/pages/x/api/charts/chart-container-pro.json
@@ -1,9 +1,5 @@
 {
   "props": {
-    "series": {
-      "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" },
-      "required": true
-    },
     "colors": {
       "type": { "name": "union", "description": "Array&lt;string&gt;<br>&#124;&nbsp;func" },
       "default": "blueberryTwilightPalette"
@@ -17,12 +13,18 @@
         "description": "{ dataIndex?: number, seriesId?: number<br>&#124;&nbsp;string }"
       }
     },
+    "id": { "type": { "name": "string" } },
+    "initialZoom": {
+      "type": {
+        "name": "arrayOf",
+        "description": "Array&lt;{ axisId: number<br>&#124;&nbsp;string, end: number, start: number }&gt;"
+      }
+    },
     "margin": {
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "onHighlightChange": {
       "type": { "name": "func" },
@@ -38,7 +40,7 @@
         "describedArgs": ["zoomData"]
       }
     },
-    "plugins": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
+    "series": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
     "skipAnimation": { "type": { "name": "bool" } },
     "width": { "type": { "name": "number" } },
     "xAxis": {
@@ -58,12 +60,6 @@
         "name": "arrayOf",
         "description": "Array&lt;{ colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, id?: string, max?: number, min?: number }&gt;"
       }
-    },
-    "zoom": {
-      "type": {
-        "name": "arrayOf",
-        "description": "Array&lt;{ axisId: number<br>&#124;&nbsp;string, end: number, start: number }&gt;"
-      }
     }
   },
   "name": "ChartContainerPro",

diff --git a/docs/pages/x/api/charts/chart-container.json b/docs/pages/x/api/charts/chart-container.json
@@ -1,9 +1,5 @@
 {
   "props": {
-    "series": {
-      "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" },
-      "required": true
-    },
     "colors": {
       "type": { "name": "union", "description": "Array&lt;string&gt;<br>&#124;&nbsp;func" },
       "default": "blueberryTwilightPalette"
@@ -17,12 +13,12 @@
         "description": "{ dataIndex?: number, seriesId?: number<br>&#124;&nbsp;string }"
       }
     },
+    "id": { "type": { "name": "string" } },
     "margin": {
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "onHighlightChange": {
       "type": { "name": "func" },
@@ -31,7 +27,7 @@
         "describedArgs": ["highlightedItem"]
       }
     },
-    "plugins": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
+    "series": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
     "skipAnimation": { "type": { "name": "bool" } },
     "width": { "type": { "name": "number" } },
     "xAxis": {

diff --git a/docs/pages/x/api/charts/chart-data-provider.json b/docs/pages/x/api/charts/chart-data-provider.json
@@ -1,56 +1,16 @@
 {
   "props": {
-    "series": {
-      "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" },
-      "required": true
-    },
-    "colors": {
-      "type": { "name": "union", "description": "Array&lt;string&gt;<br>&#124;&nbsp;func" },
-      "default": "blueberryTwilightPalette"
-    },
-    "dataset": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
-    "height": { "type": { "name": "number" } },
-    "highlightedItem": {
-      "type": {
-        "name": "shape",
-        "description": "{ dataIndex?: number, seriesId?: number<br>&#124;&nbsp;string }"
-      }
-    },
-    "margin": {
-      "type": {
-        "name": "shape",
-        "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
-    },
-    "onHighlightChange": {
-      "type": { "name": "func" },
-      "signature": {
-        "type": "function(highlightedItem: HighlightItemData | null) => void",
-        "describedArgs": ["highlightedItem"]
-      }
-    },
-    "plugins": { "type": { "name": "arrayOf", "description": "Array&lt;object&gt;" } },
-    "skipAnimation": { "type": { "name": "bool" } },
-    "width": { "type": { "name": "number" } },
-    "xAxis": {
-      "type": {
-        "name": "arrayOf",
-        "description": "Array&lt;{ classes?: object, colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, disableLine?: bool, disableTicks?: bool, domainLimit?: 'nice'<br>&#124;&nbsp;'strict'<br>&#124;&nbsp;func, fill?: string, hideTooltip?: bool, id?: number<br>&#124;&nbsp;string, label?: string, labelStyle?: object, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, position?: 'bottom'<br>&#124;&nbsp;'top', reverse?: bool, scaleType?: 'band'<br>&#124;&nbsp;'linear'<br>&#124;&nbsp;'log'<br>&#124;&nbsp;'point'<br>&#124;&nbsp;'pow'<br>&#124;&nbsp;'sqrt'<br>&#124;&nbsp;'time'<br>&#124;&nbsp;'utc', slotProps?: object, slots?: object, stroke?: string, sx?: Array&lt;func<br>&#124;&nbsp;object<br>&#124;&nbsp;bool&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object, tickInterval?: 'auto'<br>&#124;&nbsp;array<br>&#124;&nbsp;func, tickLabelInterval?: 'auto'<br>&#124;&nbsp;func, tickLabelPlacement?: 'middle'<br>&#124;&nbsp;'tick', tickLabelStyle?: object, tickMaxStep?: number, tickMinStep?: number, tickNumber?: number, tickPlacement?: 'end'<br>&#124;&nbsp;'extremities'<br>&#124;&nbsp;'middle'<br>&#124;&nbsp;'start', tickSize?: number, valueFormatter?: func }&gt;"
-      }
-    },
-    "yAxis": {
-      "type": {
-        "name": "arrayOf",
-        "description": "Array&lt;{ classes?: object, colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, disableLine?: bool, disableTicks?: bool, domainLimit?: 'nice'<br>&#124;&nbsp;'strict'<br>&#124;&nbsp;func, fill?: string, hideTooltip?: bool, id?: number<br>&#124;&nbsp;string, label?: string, labelStyle?: object, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, position?: 'left'<br>&#124;&nbsp;'right', reverse?: bool, scaleType?: 'band'<br>&#124;&nbsp;'linear'<br>&#124;&nbsp;'log'<br>&#124;&nbsp;'point'<br>&#124;&nbsp;'pow'<br>&#124;&nbsp;'sqrt'<br>&#124;&nbsp;'time'<br>&#124;&nbsp;'utc', slotProps?: object, slots?: object, stroke?: string, sx?: Array&lt;func<br>&#124;&nbsp;object<br>&#124;&nbsp;bool&gt;<br>&#124;&nbsp;func<br>&#124;&nbsp;object, tickInterval?: 'auto'<br>&#124;&nbsp;array<br>&#124;&nbsp;func, tickLabelInterval?: 'auto'<br>&#124;&nbsp;func, tickLabelPlacement?: 'middle'<br>&#124;&nbsp;'tick', tickLabelStyle?: object, tickMaxStep?: number, tickMinStep?: number, tickNumber?: number, tickPlacement?: 'end'<br>&#124;&nbsp;'extremities'<br>&#124;&nbsp;'middle'<br>&#124;&nbsp;'start', tickSize?: number, valueFormatter?: func }&gt;"
-      }
-    },
-    "zAxis": {
-      "type": {
-        "name": "arrayOf",
-        "description": "Array&lt;{ colorMap?: { colors: Array&lt;string&gt;, type: 'ordinal', unknownColor?: string, values?: Array&lt;Date<br>&#124;&nbsp;number<br>&#124;&nbsp;string&gt; }<br>&#124;&nbsp;{ color: Array&lt;string&gt;<br>&#124;&nbsp;func, max?: Date<br>&#124;&nbsp;number, min?: Date<br>&#124;&nbsp;number, type: 'continuous' }<br>&#124;&nbsp;{ colors: Array&lt;string&gt;, thresholds: Array&lt;Date<br>&#124;&nbsp;number&gt;, type: 'piecewise' }, data?: array, dataKey?: string, id?: string, max?: number, min?: number }&gt;"
-      }
-    }
+    "colors": { "type": { "name": "any" }, "default": "blueberryTwilightPalette" },
+    "dataset": { "type": { "name": "any" } },
+    "height": { "type": { "name": "any" } },
+    "highlightedItem": { "type": { "name": "any" } },
+    "id": { "type": { "name": "any" } },
+    "margin": { "type": { "name": "any" } },
+    "onHighlightChange": { "type": { "name": "any" } },
+    "series": { "type": { "name": "any" } },
+    "skipAnimation": { "type": { "name": "any" } },
+    "width": { "type": { "name": "any" } },
+    "zAxis": { "type": { "name": "any" } }
   },
   "name": "ChartDataProvider",
   "imports": [

diff --git a/docs/pages/x/api/charts/gauge-container.json b/docs/pages/x/api/charts/gauge-container.json
@@ -9,6 +9,7 @@
     "disableAxisListener": { "type": { "name": "bool" }, "default": "false" },
     "endAngle": { "type": { "name": "number" }, "default": "360" },
     "height": { "type": { "name": "number" } },
+    "id": { "type": { "name": "string" } },
     "innerRadius": {
       "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
       "default": "'80%'"
@@ -17,8 +18,7 @@
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "outerRadius": {
       "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },

diff --git a/docs/pages/x/api/charts/gauge.json b/docs/pages/x/api/charts/gauge.json
@@ -9,6 +9,7 @@
     "disableAxisListener": { "type": { "name": "bool" }, "default": "false" },
     "endAngle": { "type": { "name": "number" }, "default": "360" },
     "height": { "type": { "name": "number" } },
+    "id": { "type": { "name": "string" } },
     "innerRadius": {
       "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },
       "default": "'80%'"
@@ -17,8 +18,7 @@
       "type": {
         "name": "shape",
         "description": "{ bottom?: number, left?: number, right?: number, top?: number }"
-      },
-      "default": "object Depends on the charts type."
+      }
     },
     "outerRadius": {
       "type": { "name": "union", "description": "number<br>&#124;&nbsp;string" },