[docs] Implement the new API display design

[alexfauquette]

Links

This PR is aimed at improving the API tables browsing experience as reported in the following issues:
Fix #34085.
Fix #36544

Design reference here.

Previews

Component	Before	After
Material UI's Tabs	Before	After
Material UI's Input Adorment	Before	After
Material UI's Zoom	Before	After
Material UI's Pagination	Before	After
Material UI's Modal	Before	After
Base UI's Tab	Before	After

To-do:

• Props title
• Props description
• Update props description to match list style instead of table
• Clean CSS
• Use props table on all pages
• Transform ClassesTable into a list

It's far from perfect in terms of dev and CSS but all the basics are here.

[mui-bot]

Netlify deploy preview

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

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against b385919

[danilo-leal]

@alexfauquette maybe it's ok to make just the anchor icon container be clickable? The trade-off seems reasonable here. We also end up winning less hover state to manage, I guess!

[alexfauquette]

For the Signature section, we might need to tweak the proptypes parsing to be able to extract the signature from the rest of the description. Seems feasible. I opened a dedicated PR for that #37446

[danilo-leal]

@alexfauquette This last commit of mine, for some reason, broke the scroll anchoring 😅 Couldn't find where to fix it, so just giving you a shout out!

[alexfauquette]

@danilo-leal it's the deletion of ...theme.typography.caption, which also deletes the typography.allVariants and its scrollMarginTop: 'calc(var(--MuiDocs-header-height) + 32px)', property 😉

https://github.com/mui/material-ui/blob/88197c9fb7dd57120674bb316198c523112f9273/docs/src/modules/brandingTheme.ts/#L308

I've continued the modification by

• fixing the hash links for the special case of base API (multiple components in the same page)
• transforming the slots table into a list

[alexfauquette]

I moved type description from the body to the header of props API.

To simplify the alignment I also reorganized the default/typt/signature definitions with the following structure. It's style with display: table to ensure the alignment of all the descriptions (especially the signature)

<div className="prop-list-additional-info">
  <div className="prop-list-default-props">// This is a table row
    <div className="prop-list-title">// This is a table cell
     <p>Default:</p>
    </div>
    <div className="prop-list-content">// This is a table cell
      <code>{propDefault}</code>
    </div>
  </div>
  {/* Repeat for types and signature */}
</div>

3a735c5

[danilo-leal]

@alexfauquette this is amazing, thanks for working on this! I ended up customing the alignment a bit more, simplifying it to use flex as the additional white space on "Type", especially once there's "Signature" present, was bothering me a bit 😬 Also did some tweaking to the feedback alert, which is super exciting to have!

Lastly, is there a scalable way ⎯ instead of going case by case ⎯ to remove the <br/> on "Type" entries like these? That way, instead of them stacking up, we'd take advantage of the available horizontal space (they can stretch out).

[alexfauquette]

Thanks for the feedback item, it's much better 👌

I removed the <br>, and ok for flex instead of table

For me we are good for merging 👍

[zanivan]

Great work everyone! I really like this last iteration with the type on the same hierarchy. And nice touch by adding the alert with a way for users to provide feedback—I wonder if we shouldn't move it up on the page, at least in the first week after launch. With the new design, the pages are longer, and usually users would search for things by cmd + f on pages like this, making us lose some valuable feedback from people who don't scroll down to the end of the page.

[danilo-leal]

Interesting take! @alexfauquette had originally put it on the top of the page but I ended up thinking that moving it to the bottom would be better because if you're not in the mood to give feedback, it's extra space + scroll that we're requiring from you. Although the idea of having it on the top just for the first week isn't bad, either. But maybe we could call attention out to this one on Twitter/blog and expose that there's such a place to drop feedback?

[alexfauquette]

I had same concern as @zanivan when creating it. My thought process was the next one:

• We need to catch the attention, so let's put the message on top
• It's too noisy so let the user close the item
• But it should still allow to send the feedback
• Ho no, I'm in a trap, I need a Schrodinger alert: closed and open at the same time 🙈

Having it at the bottom seems to be a nice compromise because we have components with very small API pages for which it will be easier to see the warning.
For example mui.com/material-ui/api/card/ which gets more than 1.5k visits per day

[oliviertassinari]

@alexfauquette it looks great 👌

[oliviertassinari]

@alexfauquette I have noticed an important regression from these changes, the API pages are no longer indexed in Algolia. For example, "autoHighlight" does no longer return any results. To compare with https://v4.mui.com/.

To fix this, we need to go to https://crawler.algolia.com/admin/crawlers/739c29c8-99ea-4945-bd27-17a1df391902/configuration/edit and update the crawler configuration. Could you fix this? I could fix it but I feel it would be a great opportunity to learn more about the crawler if you haven't already. Thanks!

[oliviertassinari]

@alexfauquette Thanks, you fixed it :)

            lvl3: [".algolia-lvl3", ".markdown-body h3, .MuiApi-item-title"],

[alexfauquette]

@oliviertassinari Even better, now the autoHighligh search leads you to the props itself (not just to the props table 😍)