[docs] Improve access to the API docs from the demo pages

[danilo-leal]

Motivation

This proposal is all about the speed of navigation. What would make traversing through the docs easier? Besides improving the search experience, which we did a few months ago, merging the demo page with the component API page sounds like a good idea in this direction. For me, personally, having them separated breaks my navigation flow a bit. Additionally, the Component API folder on the side nav is sorted alphabetically whereas the Component folder is not (sorted through a specific order), which frequently gets me confused.

I also think that having everything under the same "umbrella" would facilitate learning components that are made out of several smaller ones — Text Field might be the most illustrative of this.

How this could look

Here's the first design to kick this off.

Down sides

Is there any we should consider and bring to light? What would we lose or run the risk of making worse if we moved forward with this? I can't see anything right now. I remember we talked about that not even from an SEO standpoint this would be bad. So, what else?

Related issue

The look & feel of the API table: #34085.

---

cc @mui/maintainers

[siriwatknp]

I agree with the consolidation. Just adding more info here, I would not say this is a downside but the search API won't be possible. According to our search analytics, "API" keyword is ~ 0.01%

[oliviertassinari]

Interesting thread. This problem has been a long time struggle. For instance, in 68e7a6d we moved away from the grouped approach in v0 to the split approach in v1. What I would encourage is that we benchmark with all the docs that are out there, see what are UX feels awesome. Also, I'm glad we are doing this discussion on GitHub over notion 👍 .

According to our search analytics, "API" keyword is ~ 0.01%

@siriwatknp While I agree that this data is a fact, I don't think that it has any significance for a couple of reasons:

1. When you search the Alert API, do you type "API"? I personally don't. It's faster for me to type "alert" and then to click on the API link:

2. The previous point raises another problem, we (or Algolia) didn't configure the click analytics. So we don't really know what people are clicking on after the search.
3. I think that Algolia and Google search intents are almost the same (the queries are different though, no need to prefix with mui or material UI). The popularity of the API pages varies based on the search, 3 examples that illustrate it, from all-in demo page to all-in API page

https://search.google.com/search-console/performance/search-analytics?resource_id=sc-domain%3Amui.com&metrics=CLICKS&breakdown=page&query=!mui%20typography

So in the end, I think that it's about the page views: GA, API pages are 14% of the of the usage.

https://analytics.google.com/analytics/web/?hl=en&pli=1#/report/content-pages/a106598593w159022482p160376982/explorer-table.filter=~2Fapi~2F&explorer-table.plotKeys=%5B%5D/

---

merging the demo page with the component API page sounds like a good idea in this direction

@danilo-leal It would depend on who we ask: https://twitter.com/MUI_hq/status/1122829215961948165.

cc mui/core

I have updated the cc to include everybody. We need to take into account the needs of MUI X, to design solutions that are inclusive. And maybe we can consider two different API approaches, one for simple components like Typography and one for rich components (many different moving parts) like Tabs.

the search API won't be possible

@siriwatknp Why? From what I understand this is still possible to make the API searchable.
In any case, we need the API docs to be searchable. I will veto any approaches that make, for instance, the "autocomplete renderGroup" query returns no results (or results but hidden) on Google or Algolia

[danilo-leal]

I've been playing around with more complete visualizations of how that could be. Here's an example with the Text Field component, which is one that is composed of several smaller parts. We could even think of a search bar for quickly finding a given prop. We could also think of having all the tables accordion uncollapsed by default, so we don't disrupt too much today's experience. Anyway...

[alexfauquette]

+1 for "uncollapsed by default" because it allows to search with Ctrl+F

[michaldudak]

We could use the right-hand side table of contents to link to individual components. IMO collapsing would not be very usable in this case.

[oliviertassinari]

Going back to the problem statement of this issue: "What would make traversing through the docs easier?", thoughts:

1. Stripe's execution of the API description looks better, I personally see this as a clear win:

https://stripe.com/docs/stripe-js/react#element-components

This https://mui.com/api/calendar-picker/#props

would turn into something like:

2. When landing on https://mui.com/components/button-group/, going to this section:

is tricky. Either you need to scroll a lot of content. Or you need to find "API" in the Table Of Contents, which is never at the same place between two pages.
Showing the same content but in a tab could improve the UX to find the relevant page:

We would need to give him a place in the URL, e.g. https://mui.com/components/data-grid/api/ just so that the "navigation back" action works as expected but we don't have to add it to the Google index, it can be hidden. The only blocker with this approach that I don't know how to solve is how to handle components with multiple pages, e.g. date picker, and data grid.

3. In [docs] Improve access to the API docs from the demo pages #31745 (comment), I think that:
   a. we are missing a "Component API" side nav in the left navigation because we need to be able to deep-link them in a canonical way. Some of the content in these tabs will be duplicated.
   b. there should be a single tab for the API because the props and styling API make sense per React component. "Text field" is a collection of React components.
   So structurally, I think that "merging the demo page with the component API page" would degrade the DX. However, keeping the API pages, and enhancing the demo pages to make the API content easier to consume would make sense from my perspective.

4. https://mantine.dev/core/menu/ is not a great execution IMHO. It fails at multiple things: a. documenting the API of the nested element, e.g. MenuItem API is documented nowhere. b. documenting the inheritance between multiple components (e.g. Input that has the same props as InputBase). c. documenting the API of hooks.

5. Vuetify structure to present the API of each component sounds better than what we do in production https://next.vuetifyjs.com/en/components/app-bars/#api. It gives some sense of the structure/anatomy of the component (component in the generic sense, not the React one) and how this turns into multiple React components:

6. The way react-aria handle the problem is interesting https://react-spectrum.adobe.com/react-aria/useBreadcrumbs.html

This dropdown is impossible to search index, but it's immersive, and feels relatively easy to navigate. Maybe if this was backed by proper URL pages instead of popups, it could be really great.

[siriwatknp]

I have one small point about the API table. I think we should consider changing from table to heading + description because on some pages, it is quite hard to read. Take a look at these examples:

• https://migration.mui.com/x/api/date-pickers/calendar-picker/
• https://migration.mui.com/material-ui/api/autocomplete/
• https://migration.mui.com/base/api/slider-unstyled/

One benefit is that searching method name would go directly to that section on the API page. I believe that the effort is not big, only the UI work from table to heading.

Gatsby use the heading format: https://www.gatsbyjs.com/docs/reference/config-files/gatsby-ssr/#onRenderBody

[flaviendelangle]

The X team uses a custom Api page to add a Slots section
Since the Core team is starting to use the components and componentsProps pattern a lot, it may be interesting to unify this part as well.

https://mui.com/api/data-grid/data-grid/#slots

[m4theushw]

I'm curious to see how to document components that also provide a hook, e.g. Autocomplete has useAutocomplete. The "Components props" tab seems to be only for React components.

https://developer.microsoft.com/en-us/fluentui#/controls/web/calendar is another example that keeps content and API on the same page. They even include related interfaces, click on See More at the bottom. For the DataGrid, I don't believe this is feasible due to the number of components to document and because they can also be divided into groups: components for editing, components for cells, components used in the filter panel, etc.

About where to put the description and type of each prop, https://www.apollographql.com/docs/react/api/react/hooks/#usequery also does a good job using the space available:

[danilo-leal]

Here's more iteration on the subject, I think I've covered everyone's feedback/input:

• Have one tab only for component and styling API (props and CSS)
• Tweak how each prop description, default values, and optionality are displayed
• Add Component API content in the table of contents
• Add a table to showcase component anatomy in case of components that are composed of smaller ones (text field's good example)
• Illustrate everything collapsed and one component expanded + search working

Tables collapsed, multiple components showing

Expandend component API and CSS accordions

Search result

[mbrookes]

Stripe['s] execution on the API description looks better

@oliviertassinari I do agree with the need for more horizontal space for the descriptions (#31745 (comment)), but how do you envisage the Stripe layout working foo props such as these?

https://mui.com/material-ui/api/button/#props

https://mui.com/x/api/date-pickers/calendar-picker/#props

(I'm sure that there are worse, but just for example).

Some of the content in these tabs will be duplicated

Could we perhaps keep the current URL structure for the API content, and iFrame it in the component pages?

[flaviendelangle]

Maybe #29834 could also be solved on this new api page design

[danilo-leal]

We could tackle scenarios like these with the approach I suggested above:

[mbrookes]

It looks good, but I'm not sure the default value above is the worst case, and even that might struggle to fit

[danilo-leal]

We could experiment using a larger horizontal space for the default value:

When there are multiple possible values for the prop, they'd stack horizontally then:

Edit Olivier: But the discussion on this moved to #34085.

[flaviendelangle]

It would be interesting to test this new UI with very different form of default values / description

For instance the getOpenDialogAriaText description on https://mui.com/x/api/date-pickers/date-range-picker/ has a small function code as a default value.

And for the disableCloseOnSelect is would we great to respect the line break (maybe this problem is on the X side though)

[danilo-leal]

We'd need to play around with column spacing but it seems to work as well:

Larger spacing

Smaller spacing

[oliviertassinari]

Happy to see that we are making progress with shaping what a great API DX looks like for MUI in the future :). Comments on #31745 (comment)

Have one tab only for component and styling API (props and CSS)

Agree, I think that a change as simple as moving these

links to the top of the page instead of the bottom will already greatly improve the DX. I have caught myself multiple times scrolling to the bottom of the page to find it, it costs time.

Tweak how each prop description, default values, and optionality are displayed

Agree, that this would lead to better usage of the space.

Add Component API content in the table of contents

I personally don't buy this change if it means that developers can find all the information they need staying on this page. I think that we need as much as possible a single source of truth to keep the API in its own space and push users there. The value is that we need to maintain the API pages, I fear that duplication would:

1. dilute our engineering bandwidth, leading us to ship average DX in both places instead of a great DX in one.
2. lead to a duplication of content, having confusing search results on Google and Algolia.
3. make it harder for developers to share links with their coworkers.

In https://www.oreilly.com/content/the-eight-rules-of-good-documentation/ terms, It feels like a step going too far. "try to keep thinks as DRY as possible".

The new content will ultimately lead to a lot of duplicated content. The API pages will stop returning property results on searches. Or in https://documentation.divio.com/, our component pages are guides, they suggest putting API references in a clear different space.

---

but how do you envisage the Stripe layout working foo props such as these?

@mbrookes Then maybe on 3 different lines, It would look like this:

https://mui.com/material-ui/api/button/#props

https://mui.com/x/api/date-pickers/calendar-picker/#props

---

We'd need to play around with column spacing but it seems to work as well:

@danilo-leal I agree with Michal, if we were to have 3 columns and not 2, I think that having the type of the prop as its own column would work better. This is the second thing you look at when you try to provide a value as a developer, the default value comes last, after the description. We do the same information prioritization in IntelliSense:

[mbrookes]

@oliviertassinari

I have tried to answer this in #31745 (comment).

Perhaps you could provide some examples? Because it doesn't appear so from the comment that you linked.

[oliviertassinari]

Perhaps you could provide some examples?

@mbrookes I have updated my comment to be clearer, with a visual illustration, proposing a slight modification to the design. I think that it would be great to try this change out. To see if it does deliver a superior UX as quick prototyping suggests or if it's an illusion. Considering the title of the issue: "Unify component demo page with the API page", then it could be considered a bit off-topic.

Going back to the issue itself, the more we move forward with this exploration, the more it feels that unifying the demo pages with the API strictly speaking would be a step backward.

So maybe we should rename the issue to something like "Improve API access from demo pages", it seems to be the underlying DX pain point we try to solve. Maybe moving the API links to the top of the page rather than the bottom is THE answer. In any case, we can keep this issue focused on the problem, rather than one solution.

[mbrookes]

maybe we should rename the issue to something like "Improve API access from demo pages"

👍 👍 👍

[flaviendelangle]

For me this problem is the main issue we currently have with the doc on X, the props table are totally impossible to read: #34085. I think we have a few improvements we can make to this table without doing any big structural change to the doc.

I had a look at how our main competitors our displaying their props table.

Each competitor has 2 examples, one on my QHD screen (2471px of content width) and one on my QHD screen split in half (1227px of content width).

Expand

Ant design

Source

Allows the container to take a bigger width which result in a better readability on big screen
But has the same problem when we reduce the width

Examples

Telerik

Source

Have a bigger maximum width for the container (but less than Ant Design).
Links to the doc example in the Description column.
Have a better rendering of the Description column. It handles lists for example

vs

(or maybe it's the JSDoc of our prop which is wrong)

Is even worse than us on smaller screen with a description totally eaten by the type.

Examples

Spectrum

Source

The container width is similar to ours.
I could not find very long type so the layout works well on smaller screen but it does not mean that it would handle complex type correctly.
They have interactive variables inside the types which is awesome.
They group the props in categories to be able to collapse some. For components with dozens of props it could be a very nice addition.

Examples

Blueprint

Source

The container width is similar to ours.
Save space with no default column, they just add = after the type
Like Spectrum, they have interactive varialbes inside the types but they lack correct descriptions on the one I tested.

Examples

Chakra

Source

Their prop table is in a tab of the main page, not on a dedicated page.
Not sure how this can scale with complex components that have lots of pages but it's another approach worth considering.
They don't have a table layout, which let them put several lines per component and defeat the main layouting problem we have.

Headless API

Source

The container width is similar to ours.
I could not find any complex types, it's very similar to our layout and probably has the same limits.

Examples

AG Grid

Source

Not exactly a prop table but it's similar enough.
The container width is similar to ours.
The default value is rendered below the description and the type below the name, which helps having a good layout even on smaller screen. One downside is for complex types which don't have a lot of space below the title (but the description remains super readable).

React Bootstrap

Source

I could not find any complex prop, so the layout works well even with 4 columns.