Currently OverlayPortal's declarative API is hidden behind the imperative OverlayPortalController.open() and OverlayPortalController.close() API. We couldn't find a declarative API that we could all agree on to describe the z-order of an Overlay's render children. Under the hood, the OverlayPortalController.open() method uses the current time as the z-order value, such that the last controller to call open gets to show its overlay child at the top.

One example where the declarative API becomes desirable is for implementing the menu system. All open menus should dismiss when the containing window changes size. Window resizing is propagated in the widget tree via MediaQuery changes, but OverlayPortalController.open() and OverlayPortalController.close() can't be called during widget tree rebuild because they both call setState.