[docs] V3 Migration Guide: Include notes about withMobileDialog vs useMediaQuery

[onebree]

I followed the upgrade guide from v3 to v4 last week:

https://material-ui.com/guides/migration-v3/

There was no mention of withMobileDialog being deprecated. Looks like it's mentioned in #22074, but it looks to have been deprecated after v3. Searching for the function yields no results.

I found out about useMediaQuery after reading thru related react-testing-library issues, and poking around the MUI docs themselves. Seems like it's the preferred way to handle responsive dialogs. But again, not mentioned in the upgrade guide.

https://material-ui.com/components/dialogs/#responsive-full-screen

I did find that, if you wanted to keep withMobileDiaglog in your app, you just need to adjust your test setup like so:

https://material-ui.com/components/use-media-query/#testing

I don't mind opening a pull request to update the guide, but am unsure of desired format. Seems like the guide is pretty minimal in descriptions, showing upgrade strategies (like for component refs) in other pages.

• The issue is present in the latest release.
• I have searched the issues of this repository and believe that this is not a duplicate.

[oliviertassinari]

withMobileDiaglog is getting removed in v5. We are still working on the deprecation in #23570 for v4.12.0.

[onebree]

@oliviertassinari Thank you, but even though it's not removed, it's not even searchable on the MUI v4 docs. And not mentioned in Dialogs anymore. The fact others had issues with Dialog mounting in react-testing-library (including myself), and I can't find the function in the current docs, tells me the upgrade docs are missing important info.

[oliviertassinari]

We have hidden the module from the documentation somewhere in v4. The assumption is that if you are already using it, you don't need the documentation for it and you will be notified once you upgrade to the latest version of v4 that it's deprecated and how to upgrade. You can ignore it if you upgrade from v3 to v4. It matters for the migration from v4 to v5.

[onebree]

When I upgraded to v4, there was no warning or notice about using withMobileDialog though. I was in the dark for a couple of days as to why my tests failed. I happened to stumble and put the pieces together myself that this function is losing support, and to move to a hook instead. Like I said, this was not mentioned in the upgrade docs. And IMO, somewhere should mention the drop of the HOC from docs, and point to the recommended way to perform responsive UIs now

[oliviertassinari]

Oh, that's a different issue. You are talking about how withMobileDialog uses media queries instead of the window's width. Upgrade to v4.0.0. You won't get the issue. We don't guarantee that tests don't fail when they simulate a DOM environment with things like jsdom.

[onebree]

@oliviertassinari There seems to be a misunderstanding. This is not about testing. It is in fact about docs. (Please re-add the tag)

• I am on v 4.11.0 of material-ui
• After upgrading, my Dialog instances were wrapped in withMobileDialog()
• I found that all tests touching these components, in Jest/React-Testing-Library failed
  • I understand MUI is not responsible for test failures from upgrades
• Migration Guide, or anywhere in the docs, mention how useMediaQuery is preferred over withMobileDialog
• In fact, withMobileDialog is no where in the docs anymore, making it difficult to know, without reading every related doc, that MUI v4 has a different preferred pattern for responsive dialogs

Proposal: Update somewhere in the docs how useMediaQuery is now preferred over the old withMobileDialog. Preferably in the migration docs, as this was no problem in v3.

Reason: I am not alone in finding problems after the upgrade. I am sure more folks will continue to run into the same problem as me, until v5 is fully released. Even then, people may try to upgrade v3 -> v4 -> v5, and then still run into my issue.

[oliviertassinari]

I found that all tests touching these components, in Jest/React-Testing-Library failed

You need https://material-ui.com/components/use-media-query/#testing to solve the issue. withMobileDialog uses withWidth that uses useMediaQuery.