DropdownWidget and several others have an $overlay config parameter, but the documentation about it is not optimal:
- Unless you read through all parameters, it's not clear that this can be used to "escape" from a dialog or similar restriction. I actually learned that this is possible from https://doc.wikimedia.org/oojs-ui/master/demos/#dialogs-mediawiki-ltr-desktop. IMHO this is common enough to mention it in the main description on https://doc.wikimedia.org/oojs-ui/master/js/#!/api/OO.ui.DropdownWidget and on https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options.
- It's not clear what elements should be used as $overlay.
- For dialogs, I learned from the demo, to use the $overlay property of the dialog. This property isn't even mentioned on https://doc.wikimedia.org/oojs-ui/master/js/#!/api/OO.ui.Window or any inherited class. It should be properly documented.
- For other situations (e.g. BookletLayout) I actually don't know what element to use. E.g. using $( 'body' ) has all sorts of strange behaviour, and I don't know whether these are bugs in OOjs UI, or whether I shouldn't even think about using the body as overlay element. This should be made clear in the documentation.