[docs][base] Show components & hooks API on the components page #35938

mnajdova · 2023-01-24T20:20:57Z

This PR converts the ~~MUI Base~~ Base UI's components pages to have tabs for the components & hooks apis. Changes done to make this possible:

The docs:api cmd now generates the following pages:
- /react-componentName/index.js - the initial page for the component (demos)
- /react-componentName/[docsTab]/index.js - the page for the tabs APIs (components & hooks)
The new pages use the getLayout method, that allows us to define the app frame once, so that the transition between the tabs (and pages for that matter) is smoother. The files are generated based on the md files and currently run only for the base docs, more specifically for the pages inside the components/ folder.
The JSDocs of the components & hooks are also updated to point to the new API locations.
the scripts are updated to not generate the old API pages, and they have been removed

Preview

Demos page: https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/
Components API: https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/components-api
Hooks API: https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/hooks-api

Community feedback: #36204

Signed-off-by: Marija Najdova <mnajdova@gmail.com>

…dova/material-ui into docs/build-hooks-interfaces

…-value

mui-bot · 2023-01-24T20:24:00Z

Netlify deploy preview

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against 1ddf6e8

danilo-leal

Looks great to me ⎯ excellent work 🎉

flaviendelangle · 2023-03-28T09:59:42Z

Should we remove the Default column when it's fully empty ?

mnajdova · 2023-03-28T10:48:19Z

Should we remove the Default column when it's fully empty?

That makes sense 👍, I will create a separate PR for this, as it would affect other API pages too, just to make sure I won't create regressions.

flaviendelangle

Looks great 🎂

oliviertassinari

Alright, we are getting there :)!

I did a deep dive into the changes with the thing that I could find, in addition to the inline comments:

[docs] Fix double API page redirection #36743 fixed double redirections
[docs] Improve side nav scroll into view #36732 is a fun one I took care of, this isn't directly related to these changes.

I think that it could be interesting to explore how we can have generic tab support in the docs infra, like https://stripe.com/docs/quotes/create?testing-method=without-code. Right now, it feels like it's not something MUI X or Toolpad could use.

In terms of UX, now that I can fully play with it, I'm personally in the camp of one page per exported module to consume the content is better/simpler to use. As we are making each of these pages more comprehensive (= unreadable toc, and = more scroll to), I think that this reinforces this feeling. However, the new UI to access the reference is better.

I think that as a next step, it would be great to move https://deploy-preview-35938--material-ui.netlify.app/material-ui/react-button/#api to the top of the page so it can be easily accessed (e.g. https://vuetifyjs.com/en/components/expansion-panels/#api) and to wait to see how developers are enjoying the different UX. Maybe try to move Joy UI as well, if we see that Algolia & Google search & the other user journey with Base UI works OK. But I think that it would make more impact to invest time in fixing #34085 considering the volume of requests we have about it and that it's not too big of a task.

docs/data/base/pagesApi.js

docs/data/base/pages.ts

oliviertassinari · 2023-04-01T12:13:57Z

packages/mui-base/src/useBadge/useBadge.ts

- * - [useBadge API](https://mui.com/base/api/use-badge/)
+ * - [useBadge API](https://mui.com/base/react-badge/hooks-api/#use-badge)


If we ever need to revert this change, we will need to get innovative with anchor redirections. anchors are never sent from the client to the server.

oliviertassinari · 2023-04-01T12:15:51Z

docs/translations/translations.json

+    "/base/react-badge/components-api": "BadgeUnstyled",
+    "/base/react-button/components-api": "ButtonUnstyled",
+    "/base/react-click-away-listener/components-api": "ClickAwayListener",
+    "/base/react-focus-trap/components-api": "FocusTrap",
+    "/base/react-form-control/components-api": "FormControlUnstyled",
+    "/base/react-input/components-api": "InputUnstyled",
+    "/base/react-menu/components-api": "MenuUnstyled",
+    "/base/react-modal/components-api": "ModalUnstyled",
+    "/base/react-no-ssr/components-api": "NoSsr",
+    "/base/react-select/components-api": "SelectUnstyled",
+    "/base/react-popper/components-api": "PopperUnstyled",
+    "/base/react-portal/components-api": "Portal",
+    "/base/react-slider/components-api": "SliderUnstyled",
+    "/base/react-snackbar/components-api": "SnackbarUnstyled",
+    "/base/react-switch/components-api": "SwitchUnstyled",
+    "/base/react-tabs/components-api": "TabsUnstyled",
+    "/base/react-table-pagination/components-api": "TablePaginationUnstyled",
+    "/base/react-textarea-autosize/components-api": "TextareaAutosize",
+    "/base/react-badge/hooks-api": "useBadge",
+    "/base/react-button/hooks-api": "useButton",
+    "/base/react-form-control/hooks-api": "useFormControlUnstyledContext",
+    "/base/react-input/hooks-api": "useInput",
+    "/base/react-menu/hooks-api": "useMenuItem",
+    "/base/react-select/hooks-api": "useSelect",
+    "/base/react-slider/hooks-api": "useSlider",
+    "/base/react-snackbar/hooks-api": "useSnackbar",
+    "/base/react-switch/hooks-api": "useSwitch",
+    "/base/react-tabs/hooks-api": "useTabsList",


API module names shouldn't be translated

Suggested change

"/base/react-badge/components-api": "BadgeUnstyled",

"/base/react-button/components-api": "ButtonUnstyled",

"/base/react-click-away-listener/components-api": "ClickAwayListener",

"/base/react-focus-trap/components-api": "FocusTrap",

"/base/react-form-control/components-api": "FormControlUnstyled",

"/base/react-input/components-api": "InputUnstyled",

"/base/react-menu/components-api": "MenuUnstyled",

"/base/react-modal/components-api": "ModalUnstyled",

"/base/react-no-ssr/components-api": "NoSsr",

"/base/react-select/components-api": "SelectUnstyled",

"/base/react-popper/components-api": "PopperUnstyled",

"/base/react-portal/components-api": "Portal",

"/base/react-slider/components-api": "SliderUnstyled",

"/base/react-snackbar/components-api": "SnackbarUnstyled",

"/base/react-switch/components-api": "SwitchUnstyled",

"/base/react-tabs/components-api": "TabsUnstyled",

"/base/react-table-pagination/components-api": "TablePaginationUnstyled",

"/base/react-textarea-autosize/components-api": "TextareaAutosize",

"/base/react-badge/hooks-api": "useBadge",

"/base/react-button/hooks-api": "useButton",

"/base/react-form-control/hooks-api": "useFormControlUnstyledContext",

"/base/react-input/hooks-api": "useInput",

"/base/react-menu/hooks-api": "useMenuItem",

"/base/react-select/hooks-api": "useSelect",

"/base/react-slider/hooks-api": "useSlider",

"/base/react-snackbar/hooks-api": "useSnackbar",

"/base/react-switch/hooks-api": "useSwitch",

"/base/react-tabs/hooks-api": "useTabsList",

oliviertassinari · 2023-04-01T12:20:01Z

docs/src/modules/utils/helpers.ts

 export function pageToTitleI18n(page: Page, t: Translate): string | null {
  const path = page.subheader || page.pathname;
-  return t(`pages.${path}`, { ignoreWarning: true }) || pageToTitle(page);
+  return page.query
+    ? pageToTitle(page)
+    : t(`pages.${path}`, { ignoreWarning: true }) || pageToTitle(page);
 }


We have a problem with the page titles, this will be disorienting in Algolia and Google Search results:

https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/
"Unstyled React Tabs components - MUI Base"

https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/components-api/
"Unstyled React Tabs components - MUI Base"

https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/hooks-api/
"Unstyled React Tabs components - MUI Base"

oliviertassinari · 2023-04-01T12:52:41Z

docs/pages/_app.js


  return (
    <AppWrapper emotionCache={emotionCache} pageProps={pageProps}>
-      <Component {...pageProps} />
+      {getLayout(<Component {...pageProps} />)}


This makes the page transition feel a lot better 👌. I think to deploy everywhere: https://www.notion.so/mui-org/Fix-page-transition-slowness-212d920a9ab245f08ac3a2aea874f1bc.

It would solve the "Out of scope" part of #36732. I'm so excited about this fix! cc @siriwatknp @mnajdova

oliviertassinari · 2023-04-01T13:01:26Z

docs/pages/base/react-badge/[docsTab]/index.js

+  };
+};
+
+export const getStaticProps = () => {


In the past, we struggled to make the translation work with this approach: vercel/next.js#15315 (comment), it was not possible.

I'm curious to see which translation approach React takes in reactjs/react.dev#4135.

docs/src/modules/components/AppLayoutDocs.js

oliviertassinari · 2023-04-01T13:04:32Z

docs/src/modules/components/MarkdownDocsV2.js

+      disableToc={disableToc}
+      location={location}
+      title={title}
+      toc={activeToc}


https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/components-api/#tabs-unstyled highlights the wrong header:

docs/data/base/pagesApi.js

oliviertassinari · 2023-04-07T17:00:43Z

The latest ahrefs crawl surfaces an interesting bug: https://app.ahrefs.com/site-audit/3524616/59/data-explorer?columns=pageRating%2Curl%2Ctraffic%2ChttpCode%2Cdepth%2Ccompliant%2CincomingAllLinks%2Corigin&filterId=91013c8aafad4fe1f7a0ad504eccad42&issueId=c64da643-d0f4-11e7-8ed1-001e67ed4656&sorting=-pageRating

Open https://mui.com/material-ui/react-tabs/#api
Click on

Click on it, it's a 404 (https://mui.com/base/api/tabs-list-unstyled/)

I think that we should fix the redirection that leads to a 404, and then, update all the links in the markdown so there are no redirections.

mnajdova added 26 commits January 14, 2023 13:45

[docs] Add hooks API pages

f1fde60

more progress

e079c7c

more fixes

0ae093f

link hooks in the component's API section

092f1de

fix default values

6c1ee0e

cleanup

1f69369

link other hooks on the unstyled component pages

542ce9f

add annotation on the hooks

a9400c4

small fixes

7c2c19b

Add return value generation logic & UseButtonReturnValue interface

dc56c8e

Fix useMenuItem ts issue

bd3d393

Fix UseButtonReturnValue

7f56ce9

Update docs/src/modules/components/AppNavDrawer.js

a5e213b

Signed-off-by: Marija Najdova <mnajdova@gmail.com>

yarn docs:api

ce67b74

Merge branch 'docs/build-hooks-interfaces' of https://github.com/mnaj…

6f0c397

…dova/material-ui into docs/build-hooks-interfaces

updated parseMarkdown tests

4a38c6a

Improve the demos link to point to the hook section

aa31bd7

Resolve comments from backlog grooming

54e5e19

Renamed inputParams to parameters, renamed returnValue hash to return…

a5c2670

…-value

Show optional abbr for return value

1406831

Extract the PropertiesTable in a standalone component

ebf4760

Merge branch 'master' into docs/build-hooks-interfaces

516d805

prettier

ae9aa4a

Renamed Sidebar Component API group to API

00c387c

[poc] API tabs in the components pages

9109535

Make all tabs working

818db5f

mnajdova added docs Improvements or additions to the documentation proof of concept Studying and/or experimenting with a to be validated approach labels Jan 24, 2023

link component API page to the correct tab

9df6d1f

danilo-leal added 2 commits March 28, 2023 06:41

last batch of design tweaks

db913bd

one more detail

9c8b350

danilo-leal approved these changes Mar 28, 2023

View reviewed changes

mnajdova requested a review from siriwatknp March 28, 2023 10:46

flaviendelangle approved these changes Mar 28, 2023

View reviewed changes

mnajdova added 3 commits March 29, 2023 09:34

Merge branch 'master' into poc/hook-api-links

051e12b

add useOption hook in the docs

e4f723b

add redirects

4ae86fe

mnajdova added the package: base-ui Specific to @mui/base label Mar 29, 2023

Merge branch 'master' into poc/hook-api-links

1ddf6e8

mnajdova mentioned this pull request Mar 31, 2023

[docs] Hide the default API column if it's empty #36715

Merged

mnajdova merged commit dea13c8 into mui:master Mar 31, 2023
8 checks passed

This was referenced Mar 31, 2023

[docs] Improve side nav scroll into view #36732

Merged

[docs] Fix double API page redirection #36743

Merged

oliviertassinari reviewed Apr 1, 2023

View reviewed changes

siriwatknp mentioned this pull request Apr 3, 2023

[docs] Remove hash property and leverage pathname #36764

Merged

1 task

ZeeshanTamboli mentioned this pull request Apr 4, 2023

[docs] Remove redundant files and fix regression #36775

Merged

1 task

This was referenced Apr 10, 2023

[docs] Improve perf on tab APIs #36832

Merged

[docs] Fix base API redirects #36833

Merged

mj12albert mentioned this pull request Apr 18, 2023

[docs] useAutocomplete Base UI page not found #36884

Closed

1 task

This was referenced Apr 23, 2023

[docs] Fix 404 links #36969

Merged

[docs] Fix small regressions API pages #36972

Merged

[base] Remove unstyled suffix from Base components + Codemod script #36873

Merged

ZeeshanTamboli mentioned this pull request May 22, 2023

[docs] Fix branding theme tabs and navigation bar regressions #37362

Merged

1 task

oliviertassinari mentioned this pull request Jul 19, 2023

[website] Fix a few regression #38050

Merged

oliviertassinari mentioned this pull request Jan 2, 2024

[docs] Fix 301 link to Base UI #40396

Merged

oliviertassinari mentioned this pull request Feb 15, 2024

[docs-infra] Fix Base UI API tabs layout regresions #41122

Open

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs][base] Show components & hooks API on the components page #35938

[docs][base] Show components & hooks API on the components page #35938

mnajdova commented Jan 24, 2023 •

edited by oliviertassinari

mui-bot commented Jan 24, 2023 •

edited

danilo-leal left a comment

flaviendelangle commented Mar 28, 2023

mnajdova commented Mar 28, 2023

flaviendelangle left a comment

oliviertassinari left a comment •

edited

oliviertassinari Apr 1, 2023

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari commented Apr 7, 2023 •

edited by mnajdova

		* - [useBadge API](https://mui.com/base/api/use-badge/)
		* - [useBadge API](https://mui.com/base/react-badge/hooks-api/#use-badge)

[docs][base] Show components & hooks API on the components page #35938

[docs][base] Show components & hooks API on the components page #35938

Conversation

mnajdova commented Jan 24, 2023 • edited by oliviertassinari

Preview

mui-bot commented Jan 24, 2023 • edited

Netlify deploy preview

Bundle size report

danilo-leal left a comment

Choose a reason for hiding this comment

flaviendelangle commented Mar 28, 2023

mnajdova commented Mar 28, 2023

flaviendelangle left a comment

Choose a reason for hiding this comment

oliviertassinari left a comment • edited

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023 • edited

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023 • edited

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023 • edited

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023 • edited

Choose a reason for hiding this comment

oliviertassinari Apr 1, 2023 • edited

Choose a reason for hiding this comment

oliviertassinari commented Apr 7, 2023 • edited by mnajdova

mnajdova commented Jan 24, 2023 •

edited by oliviertassinari

mui-bot commented Jan 24, 2023 •

edited

oliviertassinari left a comment •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari Apr 1, 2023 •

edited

oliviertassinari commented Apr 7, 2023 •

edited by mnajdova