Description
Docs feedback
How can we improve Base UI documentation?
As I implement my own styled modal dialog component with Base UI, I am wondering when to use Dialog and when to use AlertDialog. I've read the MDN pages for the dialog and alertdialog roles, but I feel like the Base UI docs should have a section about the actual differences in behavior, as implemented in Base UI. Otherwise, the user is left comparing both pages and noticing that, for example, Dialog.Root has dismissible and modal props while AlertDialog.Root doesn't (why? I guess because alert dialogs are always modal and never dismissible, but perhaps that should be said) and that AlertDialog doesn't seem to have the same support for nested dialogs (or maybe the documentation of that feature is just less complete on the AlertDialog page?).
If the only difference is the default value of (Alert)Dialog.Popup's role attribute and the absence of some props in AlertDialog because it doesn't support dismissibility or non-modality for accessibility reasons, I wonder if it's acceptable, for my reusable styled dialog component, to always use Base UI's Dialog and accept a role prop which, when set to alertdialog, would set Dialog.Root's dismissible prop to false and override Dialog.Popup's role? It feels cleaner than conditionally rendering Dialog or AlertDialog parts everywhere.
Thank you!