[docs] Update buildAPI script to handle the "styled" components

[mnajdova]

This PR prepares necessary changes for generating the CSS and Component name sections in the docs file for the components that does not use withStyles and does not contain the classes prop. It extract this information based on the JSON data available at docs/data/component-name.json.

[mui-pr-bot]

Details of bundle changes

Generated by 🚫 dangerJS against 99bae46

[oliviertassinari]

On a related note, the changes make me wonder if we need a section for the components prop, to describe what each component do, or maybe an interactive playground that change the color background could do the trict.

[eps1lon]

This won't do anything. JSDOC for literals is ignored: microsoft/TypeScript#25499.

[mnajdova]

Aha, now I understand why I didn't have these on the node directly, so I had to iterate all leadingComments and see which one is right before the specific classKey - see #23370 (comment) I am open to other ideas of how to do this.

[mbrookes]

On hold pending #23214

[eps1lon]

We should use a more approachable format for this documentation. Encoding it in types where it isn't useful at all is not helpful long-term.

It make sense to encode in types if it has a direct impact and a first-class API. Extracting it manually is too brittle.

[mnajdova]

We should use a more approachable format for this documentation. Encoding it in types where it isn't useful at all is not helpful long-term.

It make sense to encode in types if it has a direct impact and a first-class API. Extracting it manually is too brittle.

Do you have some suggestion for better alternative? We could do it manually, but I don't think that is a better alternative at this moment. I understand that adding comments on the union type is not he best option, but I don't have better ideas to be honest.

[eps1lon]

I think we should just fork it entirely. The "CSS" section doesn't make much sense for the unstyled classnames:

• rule name is irrelevant
• classes object is not implemented
• mention of implementation is not helpful since the definition of these rules is spread throughout the implementation.
  It might be impossible to extract statically without using actual types.

It seems to me a minimal approach at first is better suited i.e. don't abstract before we know there's an abstraction:

• classnames with description in JSON
• separate function for generating the CSS section

Over time we move more and more components to that new format and during that time we'll see what makes more sense. Abstracting it just for one component might not pay off long term.

[mnajdova]

@eps1lon what do you think of these changes - mnajdova#12

[mnajdova]

It seems to me a minimal approach at first is better suited i.e. don't abstract before we know there's an abstraction:

• classnames with description in JSON
• separate function for generating the CSS section

Over time we move more and more components to that new format and during that time we'll see what makes more sense. Abstracting it just for one component might not pay off long term.

@eps1lon done let's do final round of reviews to unblock #23308

Note: You mention that we don't need the classes key as we do not have the classes prop, but we DO NEED them for the theme overrides, so we should keep them. Example:

const theme = createMuiTheme({
  components: { 
    MuiSlider: { 
      styleOverrides: { 
        colorPrimary: { // one key from the `classes`
          // some styles
        },
      },
    },
  },
});

[mbrookes]

What does the value under the class key add? It seems like redundant information that can be reconstructed.

[eps1lon]

Coninuing mnajdova#12 (comment):

Where am I mentioning the classes prop?

The docs are mentioning it:

With a rule name of the classes object prop.

-- https://deploy-preview-23370--material-ui.netlify.app/api/slider-styled/#css

The docs also still mention the implementation which is no longer helpful (and never really was):

If that's not sufficient, you can check the implementation of the component for more detail.

I still recommend completely forking the approach. This advise has been ignored while no alternative has been provided. I don't care whether you follow my proposal or someone else's. But the problems mentioned in a review should be resolved in some shape or form.

[mnajdova]

The docs are mentioning it

Alright will change the generated markdown. I wanted to keep the PR focused on how the information is extracted, not the actual content, that’s why I couldn’t understand where I am mentioning the classes prop. Will change the markdown generated together with these changes so the changes are complete.

[mnajdova]

What does the value under the class key add? It seems like redundant information that can be reconstructed.

These keys are still used under the styleOverrides in the theme. We are not documenting them on any other place as far as I know, so I think we should keep that information.

const theme = createMuiTheme({
  components: { 
    MuiSlider: { 
      styleOverrides: { 
        colorPrimary: { // one key from the `classes`
          // some styles
        },
      },
    },
  },
});

[mnajdova]

I've updated the description for the CSS section of the markdown, hopefully it is more clear now when it comes to "styled" components

[eps1lon]

Looks good. Just need to clarify what the runtime change is for.