[docs] Update buildAPI script to handle the "styled" components (#23370)

docs/data/slider-styled.json

@@ -0,0 +1,85 @@
+{
+  "name": "MuiSlider",
+  "css": {
+    "root": {
+      "class": ".MuiSlider-root",
+      "description": "Class name applied to the root element."
+    },
+    "colorPrimary": {
+      "class": ".MuiSlider-colorPrimary",
+      "description": "Class name applied to the root element if `color=\"primary\"`."
+    },
+    "colorSecondary": {
+      "class": ".MuiSlider-colorSecondary",
+      "description": "Class name applied to the root element if `color=\"secondary\"`."
+    },
+    "marked": {
+      "class": ".MuiSlider-marked",
+      "description": "Class name applied to the root element if `marks` is provided with at least one label."
+    },
+    "vertical": {
+      "class": ".MuiSlider-vertical",
+      "description": "Class name applied to the root element if `orientation=\"vertical\"`."
+    },
+    "disabled": {
+      "class": ".Mui-disabled",
+      "description": "Pseudo-class applied to the root and thumb element if `disabled={true}`."
+    },
+    "rail": {
+      "class": ".MuiSlider-rail",
+      "description": "Class name applied to the rail element."
+    },
+    "track": {
+      "class": ".MuiSlider-track",
+      "description": "Class name applied to the track element."
+    },
+    "trackFalse": {
+      "class": ".MuiSlider-trackFalse",
+      "description": "Class name applied to the track element if `track={false}`."
+    },
+    "trackInverted": {
+      "class": ".MuiSlider-trackInverted",
+      "description": "Class name applied to the track element if `track=\"inverted\"`."
+    },
+    "thumb": {
+      "class": ".MuiSlider-thumb",
+      "description": "Class name applied to the thumb element."
+    },
+    "thumbColorPrimary": {
+      "class": ".MuiSlider-thumbColorPrimary",
+      "description": "Class name applied to the thumb element if `color=\"primary\"`."
+    },
+    "thumbColorSecondary": {
+      "class": ".MuiSlider-thumbColorSecondary",
+      "description": "Class name applied to the thumb element if `color=\"secondary\"`."
+    },
+    "active": {
+      "class": ".MuiSlider-active",
+      "description": "Pseudo-class applied to the thumb element if it's active."
+    },
+    "focusVisible": {
+      "class": ".Mui-focusVisible",
+      "description": "Pseudo-class applied to the thumb element if keyboard focused."
+    },
+    "valueLabel": {
+      "class": ".MuiSlider-valueLabel",
+      "description": "Class name applied to the thumb label element."
+    },
+    "mark": {
+      "class": ".MuiSlider-mark",
+      "description": "Class name applied to the mark element."
+    },
+    "markActive": {
+      "class": ".MuiSlider-markActive",
+      "description": "Class name applied to the mark element if active (depending on the value)."
+    },
+    "markLabel": {
+      "class": ".MuiSlider-markLabel",
+      "description": "Class name applied to the mark label element."
+    },
+    "markLabelActive": {
+      "class": ".MuiSlider-markLabelActive",
+      "description": "Class name applied to the mark label element if active (depending on the value)."
+    }
+  }
+}

docs/pages/api-docs/slider-styled.md

@@ -20,7 +20,9 @@ You can learn more about the difference by [reading this guide](/guides/minimizi
 
 
 
+## Component name
 
+The `MuiSlider` name can be used for providing [default props](/customization/globals/#default-props) or [style overrides](/customization/globals/#css) at the theme level.
 
 ## Props
 
@@ -56,6 +58,36 @@ The `ref` is forwarded to the root element.
 
 Any other props supplied will be provided to the root element (native element).
 
+## CSS
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.MuiSlider-root</span> | Class name applied to the root element.
+| <span class="prop-name">colorPrimary</span> | <span class="prop-name">.MuiSlider-colorPrimary</span> | Class name applied to the root element if `color="primary"`.
+| <span class="prop-name">colorSecondary</span> | <span class="prop-name">.MuiSlider-colorSecondary</span> | Class name applied to the root element if `color="secondary"`.
+| <span class="prop-name">marked</span> | <span class="prop-name">.MuiSlider-marked</span> | Class name applied to the root element if `marks` is provided with at least one label.
+| <span class="prop-name">vertical</span> | <span class="prop-name">.MuiSlider-vertical</span> | Class name applied to the root element if `orientation="vertical"`.
+| <span class="prop-name">disabled</span> | <span class="prop-name">.Mui-disabled</span> | Pseudo-class applied to the root and thumb element if `disabled={true}`.
+| <span class="prop-name">rail</span> | <span class="prop-name">.MuiSlider-rail</span> | Class name applied to the rail element.
+| <span class="prop-name">track</span> | <span class="prop-name">.MuiSlider-track</span> | Class name applied to the track element.
+| <span class="prop-name">trackFalse</span> | <span class="prop-name">.MuiSlider-trackFalse</span> | Class name applied to the track element if `track={false}`.
+| <span class="prop-name">trackInverted</span> | <span class="prop-name">.MuiSlider-trackInverted</span> | Class name applied to the track element if `track="inverted"`.
+| <span class="prop-name">thumb</span> | <span class="prop-name">.MuiSlider-thumb</span> | Class name applied to the thumb element.
+| <span class="prop-name">thumbColorPrimary</span> | <span class="prop-name">.MuiSlider-thumbColorPrimary</span> | Class name applied to the thumb element if `color="primary"`.
+| <span class="prop-name">thumbColorSecondary</span> | <span class="prop-name">.MuiSlider-thumbColorSecondary</span> | Class name applied to the thumb element if `color="secondary"`.
+| <span class="prop-name">active</span> | <span class="prop-name">.MuiSlider-active</span> | Pseudo-class applied to the thumb element if it's active.
+| <span class="prop-name">focusVisible</span> | <span class="prop-name">.Mui-focusVisible</span> | Pseudo-class applied to the thumb element if keyboard focused.
+| <span class="prop-name">valueLabel</span> | <span class="prop-name">.MuiSlider-valueLabel</span> | Class name applied to the thumb label element.
+| <span class="prop-name">mark</span> | <span class="prop-name">.MuiSlider-mark</span> | Class name applied to the mark element.
+| <span class="prop-name">markActive</span> | <span class="prop-name">.MuiSlider-markActive</span> | Class name applied to the mark element if active (depending on the value).
+| <span class="prop-name">markLabel</span> | <span class="prop-name">.MuiSlider-markLabel</span> | Class name applied to the mark label element.
+| <span class="prop-name">markLabelActive</span> | <span class="prop-name">.MuiSlider-markLabelActive</span> | Class name applied to the mark label element if active (depending on the value).
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a [global class name](/guides/interoperability/#global-css).
+- With a rule name as part of the component's [`styleOverrides` property](/customization/components/#global-theme-override) in a custom theme.
+
 ## Demos
 
 - [Slider Styled](/components/slider-styled/)

docs/scripts/buildApi.ts

@@ -192,6 +192,40 @@ async function annotateComponentDefinition(context: {
   writeFileSync(typesFilename, typesSourceNew, { encoding: 'utf8' });
 }
 
+const camelCaseToKebabCase = (inputString: string) => {
+  const str = inputString.charAt(0).toLowerCase() + inputString.slice(1);
+  return str.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, '$1-$2').toLowerCase();
+};
+
+async function updateStylesDefinition(context: {
+  styles: ReactApi['styles'];
+  component: { filename: string };
+}) {
+  const workspaceRoot = path.resolve(__dirname, '../../');
+  const { styles, component } = context;
+
+  const componentName = path.basename(component.filename).replace(/\.js$/, '');
+  const dataFilename = `${workspaceRoot}/docs/data/${camelCaseToKebabCase(componentName)}.json`;
+
+  try {
+    const jsonDataString = readFileSync(dataFilename, { encoding: 'utf8' });
+    const jsonData = JSON.parse(jsonDataString);
+    if (jsonData) {
+      const cssData = jsonData.css;
+      const classes = Object.keys(cssData);
+      styles.classes = classes;
+      styles.name = jsonData.name;
+      styles.descriptions = classes.reduce((acc, key) => {
+        acc[key] = cssData[key].description;
+        return acc;
+      }, {} as Record<string, string>);
+    }
+  } catch (err) {
+    // Do nothing for now if the file doesn't exist
+    // This is still not supported for all components
+  }
+}
+
 async function annotateClassesDefinition(context: {
   api: ReactApi;
   component: { filename: string };
@@ -304,6 +338,15 @@ async function buildDocs(options: {
     globalClasses: {},
   };
 
+  // styled components does not have the options static
+  const styledComponent = !component?.default?.options;
+  if (styledComponent) {
+    await updateStylesDefinition({
+      styles,
+      component: componentObject,
+    });
+  }
+
   if (component.styles && component.default.options) {
     // Collect the customization points of the `classes` property.
     styles.classes = Object.keys(getStylesCreator(component.styles).create(theme)).filter(
@@ -380,9 +423,27 @@ async function buildDocs(options: {
   reactAPI.filename = componentObject.filename.replace(workspaceRoot, '');
   reactAPI.inheritance = getInheritance(testInfo, src);
 
+  if (reactAPI.styles.classes) {
+    reactAPI.styles.globalClasses = reactAPI.styles.classes.reduce((acc, key) => {
+      acc[key] = generateClassName(
+        // @ts-expect-error
+        {
+          key,
+        },
+        {
+          options: {
+            name: styles.name,
+            theme: {},
+          },
+        },
+      );
+      return acc;
+    }, {} as Record<string, string>);
+  }
+
   let markdown;
   try {
-    markdown = generateMarkdown(reactAPI);
+    markdown = generateMarkdown(reactAPI, styledComponent);
   } catch (err) {
     console.log('Error generating markdown for', componentObject.filename);
     throw err;

docs/src/modules/utils/generateMarkdown.ts

@@ -440,7 +440,7 @@ Any other props supplied will be provided to the root element (${
   return text;
 }
 
-function generateClasses(reactAPI: ReactApi) {
+function generateClasses(reactAPI: ReactApi, styledComponent: boolean) {
   if (!reactAPI.styles.classes.length) {
     return '';
   }
@@ -476,15 +476,22 @@ function generateClasses(reactAPI: ReactApi) {
 ${text}
 
 You can override the style of the component thanks to one of these customization points:
-
+${
+  styledComponent
+    ? `
+- With a [global class name](/guides/interoperability/#global-css).
+- With a rule name as part of the component's [\`styleOverrides\` property](/customization/components/#global-theme-override) in a custom theme.
+`
+    : `
 - With a rule name of the [\`classes\` object prop](/customization/components/#overriding-styles-with-classes).
 - With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
 - With a theme and an [\`overrides\` property](/customization/globals/#css).
 
 If that's not sufficient, you can check the [implementation of the component](${SOURCE_CODE_ROOT_URL}${normalizePath(
-    reactAPI.filename,
-  )}) for more detail.
-
+        reactAPI.filename,
+      )}) for more detail.
+`
+}
 `;
 }
 
@@ -552,7 +559,7 @@ import { ${reactAPI.name} } from '${source}';
 You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).`;
 }
 
-export default function generateMarkdown(reactAPI: ReactApi) {
+export default function generateMarkdown(reactAPI: ReactApi, styledComponent = false) {
   return [
     generateHeader(reactAPI),
     '',
@@ -570,6 +577,8 @@ export default function generateMarkdown(reactAPI: ReactApi) {
     generateName(reactAPI),
     generateProps(reactAPI),
     '',
-    `${generateClasses(reactAPI)}${generateInheritance(reactAPI)}${generateDemos(reactAPI)}`,
+    `${generateClasses(reactAPI, styledComponent)}${generateInheritance(reactAPI)}${generateDemos(
+      reactAPI,
+    )}`,
   ].join('\n');
 }