[docs] Add hooks API pages for MUI Base #35828

mnajdova · 2023-01-14T12:47:02Z

This PR adds logic for generating APIs for the hooks (currently used in MUI Base only). It generates the input params and return value considering the exported types from the project by using the following convention:

${hookName}Parameters - for the params
${hookname}ReturnValue - for the return value

It also adds annotation above the hooks about where the demos and API pages are (similar to the components).

Example: https://deploy-preview-35828--material-ui.netlify.app/base/api/use-button/
The API pages for the hooks are linked in the API section of the unstyled components: https://deploy-preview-35828--material-ui.netlify.app/base/react-button/#api For this to work, in the headers of the component markdown there is a new hook header.

The relevant changes are in the following files:

HookApiPage.js - similar to API page, but adjusted for hooks. Here is one example: https://deploy-preview-35828--material-ui.netlify.app/base/api/use-button/
HookApiBuilder.ts - similar to ComponentApiBuilder, but adjusted to hooks. The logic for generating the json APIs from interfaces was taken from MUI X, and slightly simplified and adjusted (in MUI Core we don't need to have distinction between different packages pro/premium etc.)
buildApi.ts - added logic for generating the hooks - invokes the previous mentioned HookApiBuilder
buildApiUtils.ts - new utils added relevant for the hooks
useButton.type.ts - for the added return value type

TODOs:

Add one hook return type & generation
Add annotation on the hook for API and demos (similar to the components)

After the PR is merged:

Review all types and add descriptions on all props
Add ReturnValue interface for all hooks
Update the useSelect and useListbox types to use generics (similar to useAutocomplete)
Add documentation for:
- https://mui.com/material-ui/react-app-bar/#usescrolltrigger-options-trigger
- https://mui.com/material-ui/react-use-media-query/?

Fixes #35792

mui-bot · 2023-01-14T12:49:37Z

	Messages
📖	Netlify deploy preview: https://deploy-preview-35828--material-ui.netlify.app/

Details of bundle changes

Generated by 🚫 dangerJS against d1ba785

docs/src/modules/components/AppNavDrawer.js

Signed-off-by: Marija Najdova <[email protected]>

mnajdova · 2023-01-18T10:02:20Z

packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts

@@ -91,7 +91,10 @@ export function writePrettifiedFile(
 * why the source includes relative url. We transform them to absolute urls with
 * this method.
 */
-async function computeApiDescription(api: ReactApi, options: { host: string }): Promise<string> {
+export async function computeApiDescription(
+  api: { description: ReactApi['description'] },


The type is simplified so that it can be used with the hooks generation too. Only the description is used in the function.

mnajdova · 2023-01-18T10:03:09Z

packages/mui-base/src/AutocompleteUnstyled/useAutocomplete.d.ts

@@ -292,6 +292,13 @@ export interface UseAutocompleteProps<
  value?: AutocompleteValue<T, Multiple, DisableClearable, FreeSolo>;
 }

+export interface UseAutocompleteParameters<


Aliasing the interface so that it matches the name pattern used for the hooks parameters.

mnajdova · 2023-01-18T10:03:55Z

packages/mui-base/src/ButtonUnstyled/useButton.types.ts

@@ -39,3 +40,33 @@ export interface UseButtonParameters {
   */
  type?: React.ButtonHTMLAttributes<HTMLButtonElement>['type'];
 }
+
+export interface UseButtonReturnValue {


Explicit type added for the useButton return value so that we can test out the generation of the API.

It's also faster for TypeScript: https://github.com/microsoft/TypeScript/wiki/Performance#using-type-annotations.

I see that it's broken with the switch too https://deploy-preview-35828--material-ui.netlify.app/base/api/use-switch/#returnValue. Would it make sense to extract these changes out of this PR and to them iteratively?

mnajdova · 2023-01-18T10:05:07Z

packages/mui-base/src/TabsUnstyled/useTabs.ts

+ *
+ * - [useTabs API](https://mui.com/base/api/use-tabs/)
+ */
+function useTabs(parameters: UseTabsParameters) {


Converted to function for consistency and simplifying the generation script.

mnajdova · 2023-01-18T10:05:23Z

packages/mui-base/src/TabsListUnstyled/useTabsList.ts

+ *
+ * - [useTabsList API](https://mui.com/base/api/use-tabs-list/)
+ */
+function useTabsList(parameters: UseTabsListParameters) {


Converted to function for consistency and simplifying the generation script.

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

michaldudak · 2023-01-23T12:22:01Z

packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts

+        return [] as any;
+      }
+
+      // Only keep `default` for bool props if it isn't 'false'.


There's no harm for us in being explicit and stating all boolean props' default values, not just non-false ones.

I followed here the logic in the components' props builder. We could fix it separately in both scripts. There was already an issue related to this - #35822

docs/src/modules/components/ApiPage.js

oliviertassinari · 2023-01-29T20:14:08Z

docs/src/modules/components/HookApiPage.js

+const Table = styled('table')(({ theme }) => {
+  const contentColor =
+    theme.palette.mode === 'dark'
+      ? alpha(theme.palette.primaryDark[900], 1)
+      : 'rgba(255, 255, 255, 1)';
+  const contentColorTransparent =
+    theme.palette.mode === 'dark'
+      ? alpha(theme.palette.primaryDark[900], 0)
+      : 'rgba(255, 255, 255, 0)';


Ah ok, you abstracted the PropretiesTable, it helps 👍. I was thinking of going all the way to create a generic top-level API component and have a JavaScript API to control its rendering.

This is MUI X page https://github.com/mui/mui-x/blob/next/docs/src/modules/components/ApiPage.js that is almost exactly the same as https://github.com/mui/material-ui/blob/next/docs/src/modules/components/ApiPage.js.

oliviertassinari

I can't see anything wrong with the UX 👌, it flows like the component API pages, developers will be happy to have these pages.

mnajdova · 2023-01-30T14:59:44Z

This is MUI X page https://github.com/mui/mui-x/blob/next/docs/src/modules/components/ApiPage.js that is almost exactly the same as https://github.com/mui/material-ui/blob/next/docs/src/modules/components/ApiPage.js.

Ah, I see your point. I haven't looked into this, but I can do a follow-up on this and see what's different between the two. We can have one component that can handle all three scenarios (components, interfaces, hooks), but I woldn't change it in this PR so that we don't have unrelated changes. I will likely need two PRs, one on X side to test out the changes.

michaldudak · 2023-01-31T10:50:06Z

The parameters table doesn't format the text as markdown. Specifically, text is backticks isn't formatted as code. See https://deploy-preview-35828--material-ui.netlify.app/base/api/use-button/#parameters and compare to https://deploy-preview-35828--material-ui.netlify.app/base/api/tab-unstyled/#props

Aside from that, it looks good!

michaldudak

I couldn't find anything wrong. Good work!

ZeeshanTamboli

It looks fantastic! 👌 I did some testing and found a few things. Maybe you are already aware of this. Just listing them so they can be tracked. Some of them can be probably be addressed in this PR.

There is no link to the demos on the useAutocomplete and useSelect pages. Its understandable for useAutocomplete since there is no AutocompleteUnstyled, but useSelect can be linked to SelectUnstyled page (the hook section)?
Menu related hooks APIs have Hooks section (plural) instead of Hook in the demos page.
Tab/Tabs related hooks don't have their respective hooks section in their unstyled components page.

flaviendelangle · 2023-02-01T08:49:57Z

Looks super solid 👌

Maybe we could group the entries in the left NavBar to improve the readability.
It's not super urgent since the alphabetical sorting already does most of the work.

mnajdova · 2023-02-01T09:45:16Z

Maybe we could group the entries in the left NavBar to improve the readability.
It's not super urgent since the alphabetical sorting already does most of the work.

It's an interesting thought, it may depend on whether we want to group them by components vs hooks (maybe add level 2 subgroup), or by concept, for e.g. having ButtonUnstyled & useButton next to each other. Happy to iterate on this later (if we decide to keep the pages vs the tabs).

mnajdova · 2023-02-01T10:04:13Z

Nice findings @ZeeshanTamboli

There is no link to the demos on the useAutocomplete and useSelect pages. Its understandable for useAutocomplete since there is no AutocompleteUnstyled, but useSelect can be linked to SelectUnstyled page (the hook section)?

Fixed the useSelect 👍

Menu related hooks APIs have Hooks section (plural) instead of Hook in the demos page.

Added logic to point to #hooks if there are multiple hooks

Tab/Tabs related hooks don't have their respective hooks section in their unstyled components page.

cc @samuelsycamore we'll need to add it.

docs/src/modules/components/PropertiesTable.js

Co-authored-by: Zeeshan Tamboli <[email protected]> Signed-off-by: Marija Najdova <[email protected]>

[docs] Add hooks API pages

f1fde60

mnajdova added the scope: docs-infra Specific to the docs-infra product label Jan 14, 2023

mnajdova added 11 commits January 16, 2023 13:26

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

mnajdova changed the title ~~[WIP][docs] Add hooks API pages~~ [docs] Add hooks API pages Jan 18, 2023

mnajdova commented Jan 18, 2023

View reviewed changes

docs/src/modules/components/AppNavDrawer.js Outdated Show resolved Hide resolved

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

a5e213b

Signed-off-by: Marija Najdova <[email protected]>

mnajdova commented Jan 18, 2023

View reviewed changes

mnajdova added 3 commits January 18, 2023 11:11

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

mnajdova changed the title ~~[docs] Add hooks API pages~~ [docs] Add hooks API pages for MUI Base Jan 18, 2023

mnajdova added docs Improvements or additions to the documentation package: base-ui Specific to @mui/base labels Jan 18, 2023

mnajdova requested review from a team January 18, 2023 10:39

Extract the PropertiesTable in a standalone component

ebf4760

mnajdova requested review from siriwatknp and oliviertassinari January 23, 2023 09:50

michaldudak reviewed Jan 23, 2023

View reviewed changes

mnajdova added 2 commits January 24, 2023 10:04

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

516d805

prettier

ae9aa4a

mnajdova requested a review from michaldudak January 24, 2023 09:32

Renamed Sidebar Component API group to API

00c387c

This was referenced Jan 24, 2023

[base] Add explicit interfaces for the return values of the public hooks #35933

Closed

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

Merged

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jan 27, 2023

oliviertassinari reviewed Jan 29, 2023

View reviewed changes

Fix name typo in component

085021e

Fix the backtikcs on the descriptions

be586f5

michaldudak approved these changes Jan 31, 2023

View reviewed changes

ZeeshanTamboli reviewed Feb 1, 2023

View reviewed changes

Zeeshan's review

09f5bba

mnajdova added 2 commits February 1, 2023 11:22

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

031c354

apply fix for default values

762d488

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 1, 2023

ZeeshanTamboli reviewed Feb 1, 2023

View reviewed changes

docs/src/modules/components/PropertiesTable.js Outdated Show resolved Hide resolved

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

d1ba785

Co-authored-by: Zeeshan Tamboli <[email protected]> Signed-off-by: Marija Najdova <[email protected]>

mnajdova merged commit 807f635 into mui:master Feb 2, 2023

mnajdova mentioned this pull request Feb 13, 2023

[docs] Fix the prop type regression on the API pages #36168

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add hooks API pages for MUI Base #35828

[docs] Add hooks API pages for MUI Base #35828

mnajdova commented Jan 14, 2023 •

edited

Loading

mui-bot commented Jan 14, 2023 •

edited

Loading

mnajdova Jan 18, 2023

mnajdova Jan 18, 2023

mnajdova Jan 18, 2023

oliviertassinari Jan 21, 2023

mnajdova Jan 18, 2023

mnajdova Jan 18, 2023

michaldudak Jan 23, 2023

mnajdova Jan 23, 2023

oliviertassinari Jan 29, 2023 •

edited

Loading

oliviertassinari left a comment •

edited

Loading

mnajdova commented Jan 30, 2023

michaldudak commented Jan 31, 2023

michaldudak left a comment

ZeeshanTamboli left a comment

flaviendelangle commented Feb 1, 2023

mnajdova commented Feb 1, 2023

mnajdova commented Feb 1, 2023

[docs] Add hooks API pages for MUI Base #35828

[docs] Add hooks API pages for MUI Base #35828

Conversation

mnajdova commented Jan 14, 2023 • edited Loading

mui-bot commented Jan 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliviertassinari Jan 29, 2023 • edited Loading

Choose a reason for hiding this comment

oliviertassinari left a comment • edited Loading

Choose a reason for hiding this comment

mnajdova commented Jan 30, 2023

michaldudak commented Jan 31, 2023

michaldudak left a comment

Choose a reason for hiding this comment

ZeeshanTamboli left a comment

Choose a reason for hiding this comment

flaviendelangle commented Feb 1, 2023

mnajdova commented Feb 1, 2023

mnajdova commented Feb 1, 2023

mnajdova commented Jan 14, 2023 •

edited

Loading

mui-bot commented Jan 14, 2023 •

edited

Loading

oliviertassinari Jan 29, 2023 •

edited

Loading

oliviertassinari left a comment •

edited

Loading