[docs-infra] Simplify CSS classes extraction in API docs generator

[michaldudak]

Currently we have mostly duplicated logic for CSS classes extraction in API docs builder and two similar fields in the resulting API description JSON files: styles and classes. This PR unifies the processing of CSS classes and gets rid of the styles field.
The format of the classes field was also changed to make it easier to use in the docs: the classes and globalClasses fields inside the classes object were changed to an object with several properties:

old:

"classes": {
  "classes": ["active", "disabled", "focusVisible"],
  "globalClasses": {
    "active": "Mui-active",
    "disabled": "Mui-disabled",
    "focusVisible": "Mui-focusVisible"
  }
}

new:

"classes": [
  {
    "key": "active",
    "className": "Mui-active",
    "description": "State class applied to the root `button` element if `active={true}`.",
    "isGlobal": true
  },
  {
    "key": "disabled",
    "className": "Mui-disabled",
    "description": "State class applied to the root `button` element if `disabled={true}`.",
    "isGlobal": true
  },
  {
    "key": "focusVisible",
    "className": "Mui-focusVisible",
    "description": "State class applied to the root `button` element if `focusVisible={true}`.",
    "isGlobal": true
  }
]

(while the description field isn't strictly necessary here, it was added to match props definitions)

The docs were adapted to use this new format.

Another change was moving the responsibility of figuring out the actual class name to the API docs builder. Previously, we had logic for this in many different places - in some cases the .Mui- prefix was added in the docs, in other in the docs builder. With this change the docs will display the class name exactly as it was defined in the JSON file, without adding any prefixes. This will allow to configure how classes are generated in the API docs builder. This was my primary motivation for this PR, as I need to customize the prefix of Base UI CSS classes.

This PR does not introduce changes visible to our users (except for a couple of corrected strings).

I recommend reviewing it by commit.

Fixes #39867

[mui-bot]

Netlify deploy preview

https://deploy-preview-39808--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against da5c2fb

[alexfauquette]

Looks much more readable like that.

I reviewed the docs part. Still need some time to review in depth the new JSON generation process, and compare the preview with the prod

[alexfauquette]

Would it be possible to use an enum here? Otherwise it's a pain when we navigate this kind of code and don't know exactly which convention is used

[michaldudak]

Could you give an example? Where exactly would you see an enum?

[alexfauquette]

I misunderstood what this property is about. I thought it was storing the mui project (core, base, joy, ...) but it's the component name

[michaldudak]

No, it's the name of the component used in style overrides object (such as MuiButton).

[alexfauquette]

With this modification, you will get a ToC with

• classes (expanded)
• slots
• classes

Should replace the hasClasses && createTocEntry('classes'), by ...getClassesToC({ }) to respect the page order

[michaldudak]

Good catch, thanks!
It won't actually ever call createTocEntry('classes') because I introduced a bug in hasClasses ;)

[alexfauquette]

This typo fix might need extra work.

In getOption and getRandomOption the loclastorage can still return 'expended'.

[michaldudak]

Right, indeed. I'll make sure it uses a default value when local storage has something unknown.

[mnajdova]

Nice work. A bit related to this, I've created this issue: #39867 we should not show the rule name for the state classes as you can't override them without bumping the specificity.

[michaldudak]

@mnajdova fixed in a394217

[michaldudak]

@alexfauquette, I'd appreciate if you could take a look at the remaining changes. I need this PR to work on #39467 further.

[alexfauquette]

Looks good 👍