[docs][Base] useAutocomplete demos & docs #37029

mj12albert · 2023-04-26T08:38:30Z

Resolves #36884
Resolves #37252

Preview: https://deploy-preview-37029--material-ui.netlify.app/base/react-autocomplete/

Adding some demos to show how to use useAutocomplete. There is no Autocomplete component yet, just the hook.

Demos

In this PR I'm aiming to add the minimal amount of topics to cover the most basic use-cases of useAutocomplete, and will exclude big topics such as freeSolo or multi.

Introduction
Minimal example (modify Material UI one)
How to render and customize options
States (value vs inputValue)
With/without Popper/Portal

I have followed (at least) the PR section of the contributing guide.

mui-bot · 2023-04-26T08:41:25Z

Netlify deploy preview

docs/data/base/components/autocomplete/autocomplete.md

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against ecada5c

mj12albert · 2023-05-11T09:28:17Z

docs/data/base/components/autocomplete/autocomplete.md

+
+{{"demo": "UseAutocompletePopper.js", "hideToolbar": true}}
+
+{{"demo": ""}}


This is a weird workaround for this:

.slice(i, rendered.length - 1)`

which I suppose is to hide the old API docs links section, but here it's just cutting off my content as there's no component: in the markdown front matter 😅

But the listbox is always opening on top.

Actualy the reason why it is cut-off is because the components header is empty, so the API section is not added. Let's instead change the logic in MarkdownDocsV2.js to do the slice only if the headers.components.length > 0. Please validate if I am correct in this assumption :)

mnajdova

Thanks for picking this up. Few thoughts:

I believe we should make all demos customized, similar to how the first one is done

Not related to this PR:

the groupedOptions should probably be just called options. when there is no need for groups the name is misleading

mj12albert · 2023-05-11T09:38:55Z

docs/data/base/components/autocomplete/autocomplete.md

+const options = ['The Godfather', 'Pulp Fiction'];
+```
+
+If you need to use a different struction for options, you must provide a function to the `getOptionLabel` prop that resolves each option to a unique value.


I modified this bit compared to the other docs (Material, Joy) because it kind of understates the importance of getOptionLabel.

The API docs just say “Used to determine the string value for a given option”, but it seems the hook heavily relies on getOptionLabel to tell different options from each other

I noticed issues kind of related to this:

Autocomplete strange suggestions when multiple options have same label value #36897

[Autocomplete] Not working properly with repeated options values #26492

mj12albert · 2023-05-12T10:15:49Z

docs/data/base/components/autocomplete/autocomplete.md

+:::warning
+Material UI and Joy UI have Autocomplete components that are built using the useAutocomplete hook, with many features that are not demo-ed here yet.
+
+To learn more about implementing a custom Autocomplete, you can explore the useAutocomplete API [docs](/base/react-autocomplete/hooks-api/), or reference the Material UI and Joy UI implementations:
+
+- [Material UI Autocomplete](/material-ui/react-autocomplete/)
+- [Joy UI Autocomplete](/joy-ui/react-autocomplete/)
+
+:::


@samuelsycamore I think the message in this callout is a little clumsy, any suggestions? 😅

Looks pretty good to me! Here's how I'd phrase that first part.

Suggested change

:::warning

Material UI and Joy UI have Autocomplete components that are built using the useAutocomplete hook, with many features that are not demo-ed here yet.

To learn more about implementing a custom Autocomplete, you can explore the useAutocomplete API [docs](/base/react-autocomplete/hooks-api/), or reference the Material UI and Joy UI implementations:

- [Material UI Autocomplete](/material-ui/react-autocomplete/)

- [Joy UI Autocomplete](/joy-ui/react-autocomplete/)

:::

:::warning

Material UI and Joy UI have Autocomplete components that are built using the `useAutocomplete` hook, and they include many features not yet described here.

To learn more about implementing a custom Autocomplete, you can explore the [`useAutocomplete` API docs](/base/react-autocomplete/hooks-api/), or reference the Material UI and Joy UI implementations:

- [Material UI Autocomplete](/material-ui/react-autocomplete/)

- [Joy UI Autocomplete](/joy-ui/react-autocomplete/)

:::

ZeeshanTamboli

Looks great!

docs/data/base/components/autocomplete/AutocompleteIntroduction.tsx

docs/data/base/components/autocomplete/autocomplete.md

mnajdova

Only one comment left, the rest looks great

mnajdova · 2023-05-31T10:18:46Z

docs/data/base/components/autocomplete/autocomplete.md

+
+{{"demo": "UseAutocompletePopper.js", "hideToolbar": true}}
+
+{{"demo": ""}}


Actualy the reason why it is cut-off is because the components header is empty, so the API section is not added. Let's instead change the logic in MarkdownDocsV2.js to do the slice only if the headers.components.length > 0. Please validate if I am correct in this assumption :)

mj12albert · 2023-06-05T07:59:27Z

instead change the logic in MarkdownDocsV2.js to do the slice only if the headers.components.length > 0

This worked and I added a comment! @mnajdova

ZeeshanTamboli

Just left two comments. Looks good. Let's ship it!

docs/data/base/components/autocomplete/UseAutocompletePopper.tsx

docs/data/base/components/autocomplete/autocomplete.md

mj12albert added docs Improvements or additions to the documentation package: base-ui Specific to @mui/base labels Apr 26, 2023

mj12albert force-pushed the base/autocomplete-docs branch 9 times, most recently from 225c441 to 28c1349 Compare April 27, 2023 16:41

mj12albert changed the title ~~[docs][Base] Autocomplete demos & docs~~ [docs][Base] useAutocomplete demos & docs Apr 27, 2023

mj12albert force-pushed the base/autocomplete-docs branch 3 times, most recently from c3d04ea to eda6e76 Compare May 10, 2023 17:05

mj12albert force-pushed the base/autocomplete-docs branch 2 times, most recently from 9a24231 to d318db4 Compare May 11, 2023 08:58

mj12albert marked this pull request as ready for review May 11, 2023 08:58

zannager requested a review from michaldudak May 11, 2023 09:18

mj12albert force-pushed the base/autocomplete-docs branch from bcf42e7 to 9078bdf Compare May 11, 2023 09:25

mj12albert commented May 11, 2023

View reviewed changes

mj12albert requested a review from a team May 11, 2023 09:30

mnajdova reviewed May 11, 2023

View reviewed changes

mj12albert commented May 11, 2023

View reviewed changes

mj12albert force-pushed the base/autocomplete-docs branch from 9078bdf to 5b49eb8 Compare May 12, 2023 09:26

mj12albert commented May 12, 2023

View reviewed changes

mj12albert requested review from mnajdova and a team May 12, 2023 10:21

ZeeshanTamboli reviewed May 22, 2023

View reviewed changes

mj12albert requested review from samuelsycamore and ZeeshanTamboli May 29, 2023 12:03

mnajdova reviewed May 31, 2023

View reviewed changes

mj12albert force-pushed the base/autocomplete-docs branch 2 times, most recently from 33c3e30 to 0228d28 Compare June 5, 2023 07:39

mj12albert requested a review from mnajdova June 5, 2023 07:59

ZeeshanTamboli approved these changes Jun 5, 2023

View reviewed changes

docs/data/base/components/autocomplete/UseAutocompletePopper.tsx Outdated Show resolved Hide resolved

docs/data/base/components/autocomplete/autocomplete.md Outdated Show resolved Hide resolved

mj12albert added 9 commits June 5, 2023 17:35

Conditionally show components API tab

8b25b81

Scaffold Base autocomplete docs page

fd6bde2

Add autocomplete intro demo

5a44745

Add minimal implementation demo

701015c

Customization section

50299bd

Tweak the demos

64c7b67

Add demo with Popper

71e432b

Add callout linking to Material & Joy

45fe038

Align the style of all demos

16c9247

mj12albert force-pushed the base/autocomplete-docs branch 3 times, most recently from d6f90f1 to 55576c1 Compare June 5, 2023 09:40

mj12albert added 3 commits June 5, 2023 17:50

Code review fixes

0da19da

Fix broken link checker

baecb82

Fix MarkdownDocsV2 to handle a hook-only page

ecada5c

mj12albert force-pushed the base/autocomplete-docs branch from 55576c1 to ecada5c Compare June 5, 2023 09:50

mj12albert merged commit 8bf37de into mui:master Jun 5, 2023
21 checks passed

mj12albert mentioned this pull request Jun 5, 2023

v5.13.4 #37508

Merged

DiegoAndai added a commit to DiegoAndai/material-ui that referenced this pull request Jun 5, 2023

Merge branch 'master' into 5.13.4 to include mui#37029

772946f

DiegoAndai added a commit to DiegoAndai/material-ui that referenced this pull request Jun 5, 2023

Add mui#37029 to CHANGELOG

b6a353a

mj12albert deleted the base/autocomplete-docs branch July 1, 2023 14:18

oliviertassinari mentioned this pull request Jan 7, 2024

[base-ui][docs] Remove redundant "Styled" prefix #40478

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs][Base] useAutocomplete demos & docs #37029

[docs][Base] useAutocomplete demos & docs #37029

mj12albert commented Apr 26, 2023 •

edited by ZeeshanTamboli

mui-bot commented Apr 26, 2023 •

edited

mj12albert May 11, 2023 •

edited

ZeeshanTamboli May 22, 2023

mnajdova May 31, 2023

mnajdova left a comment

mj12albert May 11, 2023 •

edited

mj12albert May 12, 2023

samuelsycamore May 26, 2023

ZeeshanTamboli left a comment

mnajdova left a comment

mnajdova May 31, 2023

mj12albert commented Jun 5, 2023

ZeeshanTamboli left a comment


		{{"demo": "UseAutocompletePopper.js", "hideToolbar": true}}

		{{"demo": ""}}

[docs][Base] useAutocomplete demos & docs #37029

[docs][Base] useAutocomplete demos & docs #37029

Conversation

mj12albert commented Apr 26, 2023 • edited by ZeeshanTamboli

Demos

mui-bot commented Apr 26, 2023 • edited

Netlify deploy preview

Bundle size report

mj12albert May 11, 2023 • edited

Choose a reason for hiding this comment

ZeeshanTamboli May 22, 2023

Choose a reason for hiding this comment

mnajdova May 31, 2023

Choose a reason for hiding this comment

mnajdova left a comment

Choose a reason for hiding this comment

mj12albert May 11, 2023 • edited

Choose a reason for hiding this comment

mj12albert May 12, 2023

Choose a reason for hiding this comment

samuelsycamore May 26, 2023

Choose a reason for hiding this comment

ZeeshanTamboli left a comment

Choose a reason for hiding this comment

mnajdova left a comment

Choose a reason for hiding this comment

mnajdova May 31, 2023

Choose a reason for hiding this comment

mj12albert commented Jun 5, 2023

ZeeshanTamboli left a comment

Choose a reason for hiding this comment

mj12albert commented Apr 26, 2023 •

edited by ZeeshanTamboli

mui-bot commented Apr 26, 2023 •

edited

mj12albert May 11, 2023 •

edited

mj12albert May 11, 2023 •

edited