[core] Generate slot API descriptions based on slots or `componen…

…ts` (#10879)
mui · Nov 2, 2023 · 4295a7f · 4295a7f
1 parent b0cb729
commit 4295a7f
Show file tree

Hide file tree

Showing 40 changed files with 380 additions and 130 deletions.
diff --git a/docs/pages/x/api/charts/area-element.json b/docs/pages/x/api/charts/area-element.json
@@ -3,7 +3,14 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "area",
+      "description": "The component that renders the root.",
+      "default": "AreaElementPath"
+    }
+  ],
   "name": "AreaElement",
   "imports": [
     "import { AreaElement } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/area-plot.json b/docs/pages/x/api/charts/area-plot.json
@@ -3,7 +3,14 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "area",
+      "description": "The component that renders the root.",
+      "default": "AreaElementPath"
+    }
+  ],
   "name": "AreaPlot",
   "imports": [
     "import { AreaPlot } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/bar-chart.json b/docs/pages/x/api/charts/bar-chart.json
@@ -35,7 +35,17 @@
       "default": "null"
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisContent", "description": "" },
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" },
+    { "class": null, "name": "bar", "description": "" },
+    { "class": null, "name": "itemContent", "description": "" },
+    { "class": null, "name": "legend", "description": "" },
+    { "class": null, "name": "popper", "description": "" }
+  ],
   "name": "BarChart",
   "imports": [
     "import { BarChart } from '@mui/x-charts/BarChart';",

diff --git a/docs/pages/x/api/charts/bar-plot.json b/docs/pages/x/api/charts/bar-plot.json
@@ -4,7 +4,14 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "bar",
+      "description": "The component that renders the root.",
+      "default": "BarElementPath"
+    }
+  ],
   "name": "BarPlot",
   "imports": [
     "import { BarPlot } from '@mui/x-charts/BarChart';",

diff --git a/docs/pages/x/api/charts/charts-axis.json b/docs/pages/x/api/charts/charts-axis.json
@@ -31,7 +31,12 @@
       "default": "null"
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" }
+  ],
   "name": "ChartsAxis",
   "imports": [
     "import { ChartsAxis } from '@mui/x-charts/ChartsAxis';",

diff --git a/docs/pages/x/api/charts/charts-tooltip.json b/docs/pages/x/api/charts/charts-tooltip.json
@@ -21,7 +21,11 @@
       "default": "'item'"
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisContent", "description": "" },
+    { "class": null, "name": "itemContent", "description": "" },
+    { "class": null, "name": "popper", "description": "" }
+  ],
   "name": "ChartsTooltip",
   "imports": [
     "import { ChartsTooltip } from '@mui/x-charts/ChartsTooltip';",

diff --git a/docs/pages/x/api/charts/charts-x-axis.json b/docs/pages/x/api/charts/charts-x-axis.json
@@ -37,7 +37,12 @@
     "tickNumber": { "type": { "name": "number" } },
     "tickSize": { "type": { "name": "number" }, "default": "6" }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" }
+  ],
   "name": "ChartsXAxis",
   "imports": [
     "import { ChartsXAxis } from '@mui/x-charts/ChartsXAxis';",

diff --git a/docs/pages/x/api/charts/charts-y-axis.json b/docs/pages/x/api/charts/charts-y-axis.json
@@ -37,7 +37,12 @@
     "tickNumber": { "type": { "name": "number" } },
     "tickSize": { "type": { "name": "number" }, "default": "6" }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" }
+  ],
   "name": "ChartsYAxis",
   "imports": [
     "import { ChartsYAxis } from '@mui/x-charts/ChartsYAxis';",

diff --git a/docs/pages/x/api/charts/line-chart.json b/docs/pages/x/api/charts/line-chart.json
@@ -35,7 +35,20 @@
       "default": "null"
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "area", "description": "" },
+    { "class": null, "name": "axisContent", "description": "" },
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" },
+    { "class": null, "name": "itemContent", "description": "" },
+    { "class": null, "name": "legend", "description": "" },
+    { "class": null, "name": "line", "description": "" },
+    { "class": null, "name": "lineHighlight", "description": "" },
+    { "class": null, "name": "mark", "description": "" },
+    { "class": null, "name": "popper", "description": "" }
+  ],
   "name": "LineChart",
   "imports": [
     "import { LineChart } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/line-element.json b/docs/pages/x/api/charts/line-element.json
@@ -3,7 +3,14 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "line",
+      "description": "The component that renders the root.",
+      "default": "LineElementPath"
+    }
+  ],
   "name": "LineElement",
   "imports": [
     "import { LineElement } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/line-highlight-plot.json b/docs/pages/x/api/charts/line-highlight-plot.json
@@ -3,7 +3,7 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [{ "class": null, "name": "lineHighlight", "description": "" }],
   "name": "LineHighlightPlot",
   "imports": [
     "import { LineHighlightPlot } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/line-plot.json b/docs/pages/x/api/charts/line-plot.json
@@ -3,7 +3,14 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "line",
+      "description": "The component that renders the root.",
+      "default": "LineElementPath"
+    }
+  ],
   "name": "LinePlot",
   "imports": [
     "import { LinePlot } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/mark-plot.json b/docs/pages/x/api/charts/mark-plot.json
@@ -3,7 +3,7 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [{ "class": null, "name": "mark", "description": "" }],
   "name": "MarkPlot",
   "imports": [
     "import { MarkPlot } from '@mui/x-charts/LineChart';",

diff --git a/docs/pages/x/api/charts/pie-plot.json b/docs/pages/x/api/charts/pie-plot.json
@@ -11,7 +11,10 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "pieArc", "description": "" },
+    { "class": null, "name": "pieArcLabel", "description": "" }
+  ],
   "name": "PiePlot",
   "imports": [
     "import { PiePlot } from '@mui/x-charts/PieChart';",

diff --git a/docs/pages/x/api/charts/scatter-chart.json b/docs/pages/x/api/charts/scatter-chart.json
@@ -34,7 +34,17 @@
       "default": "null"
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "axisContent", "description": "" },
+    { "class": null, "name": "axisLabel", "description": "" },
+    { "class": null, "name": "axisLine", "description": "" },
+    { "class": null, "name": "axisTick", "description": "" },
+    { "class": null, "name": "axisTickLabel", "description": "" },
+    { "class": null, "name": "itemContent", "description": "" },
+    { "class": null, "name": "legend", "description": "" },
+    { "class": null, "name": "popper", "description": "" },
+    { "class": null, "name": "scatter", "description": "" }
+  ],
   "name": "ScatterChart",
   "imports": [
     "import { ScatterChart } from '@mui/x-charts/ScatterChart';",

diff --git a/docs/pages/x/api/charts/scatter-plot.json b/docs/pages/x/api/charts/scatter-plot.json
@@ -3,7 +3,7 @@
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" }
   },
-  "slots": [],
+  "slots": [{ "class": null, "name": "scatter", "description": "" }],
   "name": "ScatterPlot",
   "imports": [
     "import { ScatterPlot } from '@mui/x-charts/ScatterChart';",

diff --git a/docs/pages/x/api/charts/spark-line-chart.json b/docs/pages/x/api/charts/spark-line-chart.json
@@ -31,7 +31,16 @@
       }
     }
   },
-  "slots": [],
+  "slots": [
+    { "class": null, "name": "area", "description": "" },
+    { "class": null, "name": "axisContent", "description": "" },
+    { "class": null, "name": "bar", "description": "" },
+    { "class": null, "name": "itemContent", "description": "" },
+    { "class": null, "name": "line", "description": "" },
+    { "class": null, "name": "lineHighlight", "description": "" },
+    { "class": null, "name": "mark", "description": "" },
+    { "class": null, "name": "popper", "description": "" }
+  ],
   "name": "SparkLineChart",
   "imports": [
     "import { SparkLineChart } from '@mui/x-charts/SparkLineChart';",

diff --git a/docs/pages/x/api/date-pickers/pickers-calendar-header.json b/docs/pages/x/api/date-pickers/pickers-calendar-header.json
@@ -2,6 +2,18 @@
   "props": {
     "classes": { "type": { "name": "object" }, "additionalInfo": { "cssApi": true } },
     "className": { "type": { "name": "string" } },
+    "components": {
+      "type": { "name": "object" },
+      "default": "{}",
+      "deprecated": true,
+      "deprecationInfo": "Please use <code>slots</code>."
+    },
+    "componentsProps": {
+      "type": { "name": "object" },
+      "default": "{}",
+      "deprecated": true,
+      "deprecationInfo": "Please use <code>slotProps</code>."
+    },
     "slotProps": { "type": { "name": "object" }, "default": "{}" },
     "slots": { "type": { "name": "object" }, "default": "{}" },
     "sx": {
@@ -12,7 +24,44 @@
       "additionalInfo": { "sx": true }
     }
   },
-  "slots": [],
+  "slots": [
+    {
+      "class": null,
+      "name": "leftArrowIcon",
+      "description": "Icon displayed in the left view switch button.",
+      "default": "ArrowLeft"
+    },
+    {
+      "class": null,
+      "name": "nextIconButton",
+      "description": "Button allowing to switch to the right view.",
+      "default": "IconButton"
+    },
+    {
+      "class": null,
+      "name": "previousIconButton",
+      "description": "Button allowing to switch to the left view.",
+      "default": "IconButton"
+    },
+    {
+      "class": null,
+      "name": "rightArrowIcon",
+      "description": "Icon displayed in the right view switch button.",
+      "default": "ArrowRight"
+    },
+    {
+      "class": null,
+      "name": "switchViewButton",
+      "description": "Button displayed to switch between different calendar views.",
+      "default": "IconButton"
+    },
+    {
+      "class": null,
+      "name": "switchViewIcon",
+      "description": "Icon displayed in the SwitchViewButton. Rotated by 180° when the open view is &#39;year&#39;.",
+      "default": "ArrowDropDown"
+    }
+  ],
   "name": "PickersCalendarHeader",
   "imports": [
     "import { PickersCalendarHeader } from '@mui/x-date-pickers/PickersCalendarHeader';",

diff --git a/docs/scripts/api/buildComponentsDocumentation.ts b/docs/scripts/api/buildComponentsDocumentation.ts
@@ -83,11 +83,13 @@ function extractSlots(options: {
     project,
     checkDeclarations: true,
     shouldResolveObject: ({ name }) => {
-      return name === 'components';
+      // TODO v7: Remove the `components` fallback once `slots` is used everywhere
+      return name === 'slots' || name === 'components';
     },
     shouldInclude: ({ name, depth }) => {
       // The keys allowed in the `components` prop have depth=2
-      return name === 'components' || depth === 2;
+      // TODO v7: Remove the `components` fallback once `slots` is used everywhere
+      return name === 'slots' || name === 'components' || depth === 2;
     },
   });
 
@@ -96,7 +98,10 @@ function extractSlots(options: {
     throw new Error(`No proptypes found for \`${displayName}\``);
   }
 
-  const componentsProps = props.types.find((type) => type.name === 'components')!;
+  const componentsProps = props.types.find(
+    // TODO v7: Remove the `components` fallback once `slots` is used everywhere
+    (type) => type.name === 'slots' || type.name === 'components',
+  )!;
   if (!componentsProps) {
     return slots;
   }
@@ -481,7 +486,8 @@ const buildComponentDocumentation = async (options: {
   /**
    * Slot descriptions.
    */
-  if (componentApi.propDescriptions.components) {
+  // TODO v7: Remove the `components` fallback once `slots` is used everywhere
+  if (componentApi.propDescriptions.slots || componentApi.propDescriptions.components) {
     const slots = extractSlots({
       filename,
       name: reactApi.name, // e.g. DataGrid

diff --git a/docs/translations/api-docs/charts/area-element.json b/docs/translations/api-docs/charts/area-element.json
@@ -25,5 +25,5 @@
       "conditions": "faded"
     }
   },
-  "slotDescriptions": {}
+  "slotDescriptions": { "area": "The component that renders the root." }
 }
diff --git a/docs/translations/api-docs/charts/area-plot.json b/docs/translations/api-docs/charts/area-plot.json
@@ -13,5 +13,5 @@
     }
   },
   "classDescriptions": {},
-  "slotDescriptions": {}
+  "slotDescriptions": { "area": "The component that renders the root." }
 }
diff --git a/docs/translations/api-docs/charts/bar-chart.json b/docs/translations/api-docs/charts/bar-chart.json
@@ -43,5 +43,15 @@
     }
   },
   "classDescriptions": {},
-  "slotDescriptions": {}
+  "slotDescriptions": {
+    "axisContent": "",
+    "axisLabel": "",
+    "axisLine": "",
+    "axisTick": "",
+    "axisTickLabel": "",
+    "bar": "",
+    "itemContent": "",
+    "legend": "",
+    "popper": ""
+  }
 }
diff --git a/docs/translations/api-docs/charts/bar-plot.json b/docs/translations/api-docs/charts/bar-plot.json
@@ -18,5 +18,5 @@
     }
   },
   "classDescriptions": {},
-  "slotDescriptions": {}
+  "slotDescriptions": { "bar": "The component that renders the root." }
 }
diff --git a/docs/translations/api-docs/charts/charts-axis.json b/docs/translations/api-docs/charts/charts-axis.json
@@ -55,5 +55,5 @@
     "left": { "description": "Styles applied to {{nodeName}}.", "nodeName": "the left axis" },
     "right": { "description": "Styles applied to {{nodeName}}.", "nodeName": "the right axis" }
   },
-  "slotDescriptions": {}
+  "slotDescriptions": { "axisLabel": "", "axisLine": "", "axisTick": "", "axisTickLabel": "" }
 }