MDL: Simplify OverlayMode and Containment API

[rolfsmeds]

Describe your motivation

MDL currently has setOverlayMode(OverlayMode) where OverlayMode is an enum of

• DRAWER: renders the detail overlay as a modal side-panel (default)
• STACK: renders the detail overlay as an overlay that completely covers the layout (or the browser viewport, with ContainmentMode.VIEWPORT)

This API has been found to be unintuitive.

MDL also has the setContainment(ContainmentMode) API where ContainmentMode is an enum of

• LAYOUT : renders the overlay and modality curtain over just the MDL (default)
• VIEWPORT : renders the overlay and modality curtain over the entire browser viewport

Figuring out how to correctly combine these APIs to achieve desired behavior has proven to be difficult.

It also feels overly complex to have 2 separate APIs to configure overlay behavior.

Describe the solution you'd like

• Combine the two APIs into one, by including containment modes in the overlay-mode options
• Rename the enum and setter to be more clearly about detail overlay
• Rename at least the STACK option to something more intuitive

enum DetailOverlayMode of options

• DRAWER : drawer with layout containment
• DRAWER_VIEWPORT : drawer with viewport containment
• FULL : overlay fully covers layout
• FULL_VIEWPORT : overlay fully covers viewport

This also allows us to later add a DIALOG or CENTERED option that renders as a centered, modal-like viewport overlay (a layout-containment dialog would hardly make sense).

(Alternatively, the enum and setter could be named DetailOverlayType to avoid confusion with the overlay state)

One aspect that might be reason to reconsider the above is if we also want to provide a way to set a separate size for the overlay (other than the detail size and FULL mode).

One way to do that, keeping the above intact, would be a setter like setDetailOverlaySize.

But we could also consider combining all 3 overlay-related aspects (mode, containment, size) into one API, but then that API would requite a totally different design because the overlay size would only be relevant for DRAWER (and if we later introduce DIALOG it would warrant two parameters: width and height).

[rolfsmeds]

Decisions:

• No DIALOG overlay mode for now – if it is later requested, it can be added as a theme variant.
• Let's introduce an API for setting a size on the overlay
• Overlay size API makes DRAWER mode unnecessary, since you can just set the size to 100% or 100vw to achieve the same.
• ContainmentMode API is still needed.

Thus, the following changes to the API:

• Remove OverlayMode API entirely
• Introduce setOverlaySize(String size) and setOverlaySize(float size, Unit unit) (overlaySize property in React)
  • If overlaySize is not set, the size set on the detail is used instead.
  • The overlay is always capped to the size of the containment viewport

[rolfsmeds]

Additional decision:
Rename Containment to OverlayContainment and setContainment to setOverlayContainment (and the WC/React property to overlayContainment) so that

• it's consistent with setOverlaySize
• its function is clearer
• IDE autocomplete will show it when you type overlay looking for overlay-specific configuration options