[material-ui] Provide more direct documentation access to props of "inherited" components

[ryancogswell]

This actually is a duplicate of #7981, but that issue is quite old and I think this would be worth re-visiting.

Summary 💡

Many Material UI components delegate to other Material UI components.

There are two main flavors of this delegation:

1. Delegating to a root element wrapped by the main component. Any props not recognized by the main component will be passed down to this root element. Example: Menu wraps Popover which in turn wraps Modal.
2. Delegating to components other than the root element. Props are generally passed to these components via a prop on the main component with a name of <InnerComponentName>Props. Example: Select leverages Menu and receives props for the Menu element via its MenuProps prop.

It is the first case (delegation to a root element) for which I think the documentation could be considerably improved.

Currently the documentation forces you to follow links to these other components in order to discover the full set of props that a component supports. Many people, especially new users of the library, do not notice (or fully understand) the "Any other props supplied will be provided to the root element" portion and miss the fact that many more props may be supported by the component. I think it would be much better for users of the documentation if all of the props from "inherited" components were included directly. So in the case of Menu, the props for Popover and Modal would be included directly in the Menu documentation. It seems like it should be doable for buildApi.js and generateMarkdown.js to be enhanced to automatically include the comprehensive props.

Examples 🌈

This Stack Overflow question shows one example of users assuming that a component (AppBar in this case) only supports the properties shown directly on its API page.

Motivation 🔦

I understand that the current way of documenting the properties was an easier approach to implement, but given the place of "Better documentation" within the roadmap priorities, I think it would be worth the additional complexity in the API doc generation (which is already aware of the inherited component) to allow users to find the comprehensive props more easily/quickly.

[oliviertassinari]

@ryancogswell Agree, we have a related thread in #17872 (comment). cc @eps1lon.

[eps1lon]

Thanks for the ping.

I already started exploring this a week ago. The idea is to extract the API into a JSON blob that can be queried at build and runtime. All the api/* routes are squashed into a single entry point that uses a custom version of dynamic routes (custom because the feature is only available in nextjs 9).

For server rendering we render the same content as before (although faster since no more markdown parsing) but progressively enhance the amount of props that can be displayed by querying at runtime.

API querying is up in the air (at build time? netlify lambda? etc). But the the separation of API data extraction and rendering (previously a single task) is almost complete. Progress can be tracked in master...eps1lon:docs/api-dynamic

[oliviertassinari]

@eps1lon I think that the JSON step is a great preliminary step. Once this infrastructure work is done, I'm wondering how we could best translate it into the documentation. We will likely need to brainstorm and explore different options.

I think that it would be great to achieve the following:

• Allow the translation of the description of the prop for Chinese users.
• Allow stronger SEO on each individual component.
• Remove the need to jump between different pages to find the information you are looking for.
• Maintain Algolia and Google search capabilities.
• Solve Aloglia confusion of results, I often search for the component page but can't and end up on the API page.

A benchmark on the different options:

• A category switch at the top of the page:
  • https://mdbootstrap.com/docs/react/components/pagination/
  • https://material.angular.io/components/autocomplete/api
  • https://mineral-ui.netlify.com/components/checkbox
  • https://react.semantic-ui.com/elements/rail/
• API at the bottom of the page
  • https://ant.design/components/table/#header
  • https://mineral-ui.netlify.com/components/checkbox
  • https://sancho-ui.com/components/tabs/
  • https://react-bootstrap.github.io/components/alerts
  • https://atlaskit.atlassian.com/packages/core/calendar
  • https://blueprintjs.com/docs/#datetime/datetimepicker
  • https://developer.microsoft.com/en-us/fabric/#/controls/web/slider
• One page per "item"
  • https://www.telerik.com/kendo-react-ui/components/scheduler/api/SchedulerProps/
  • https://js.devexpress.com/Documentation/ApiReference/Data_Visualization_Widgets/dxCircularGauge/Methods/
  • https://ej2.syncfusion.com/react/documentation/api/drop-down-list/dropDownListModel/
  • https://www.jqwidgets.com/jquery-widgets-documentation/documentation/jqxtree/jquery-tree-api.htm?search=
  • https://docs.sencha.com/extjs/7.0.0/modern/Ext.data.TreeStore.html#properties

[eps1lon]

Porting to a full React (instead of markdown) page is basically done but needs another pass that gets the API right (i.e. how to reduce the amount/number of queries cough graphql).

In addition it requires a lot of code that will be obsolete with #18441 which will also make other parts of the implementation easier. I probably open a separate PR for the API (since it can stand on its own) and propose the /api/[componentSlug].json route after next 9 is available.

[dandv]

This StackOverflow question shows one example of users assuming that a component (AppBar in this case) only supports the properties shown directly on its API page.

Not proud to admit, but I've assumed that a lot of times :)

Many people, especially new users of the library, do not notice (or fully understand) the "Any other props supplied will be provided to the root element" portion and miss the fact that many more props may be supported by the component.

Add to that HTML properties like onClick for buttons.

[croraf]

I'm trying to wrap my head around different options on how to present all possible props, and the best I can think of is the one that already is in MUI, that is:

On the component's API page show the properties that are destructured by name. At the bottom note to which underlying component are passed all other properties (that is the ones destructured with ...other).

---

Do you plan to show it like how the devtools show the styles:

where you will have a series of sections representing deeper and deeper components?

---

Will your solution require re-exposing the current pass-through properties in each MUI component's internals?

---

Also I guess in the getting started guide (or how is it called), a bigger emphasis should be put on the existence of pass-through properties.

[eps1lon]

Will your solution require re-exposing the current pass-through properties in each MUI component's internals?

The concrete UI isn't finalized. We'll probably go with some form of expand action for the current props table that adds "inherited props". But we'll also need to re-evaluate the current design. "inherited props" is too often overlooked. Though we also don't know if it is "too often". Might be that 1 in 10000 thousand only misses the hint and due to the sheer volume of user it looks to us like it is a problem.