[Feature]: Deprecate OverlayManager and replace adaptive overlay type

[sunarya-thito]

Feature Description

Remove unsolicited adaptive overlay, replace it with an option where you can choose it to be adaptive.

Problem Statement

The default adaptive behavior of showPopover on mobile is to render a bottom drawer. This mismatch between the function name and the resulting UI is a common source of confusion for new users. This behavior is managed by the OverlayManager which was initially introduced to improve the mobile UX for popup-based components (e.g., Select).

Developers can disable this adaptation by configuring the overlay handler on the OverlayManager or ShadcnApp. However, the root of the problem is a design flaw: the current function signature attempts to unify the distinct parameters for Popovers, Drawers, and Sheets. This consolidated signature has proven to be inflexible and confusing.

Proposed Solution

To resolve the API confusion and inflexibility, I propose a refactor centered on an OverlayConfiguration object. This makes responsibility from managers and handlers to the configuration object itself, making behavior explicit.

1. Remove OverlayManager and OverlayHandler: Their roles will be absorbed by the new OverlayConfiguration and a single entry-point function.
2. Introduce OverlayConfiguration: Creates a new abstract class that acts as a single source of truth for an overlay's parameters.

• Concrete implementations (e.g. PopoverConfiguration, DrawerConfiguration, SheetConfiguration) will hold only the parameters relevant to them.

3. Move logic to the configuration: The OverlayConfiguration class will be responsible for its own representation by including an abstract method:

• OverlayCompleter<T> show(BuildContext context, WidgetBuilder builder);

4. Create a unified showOverlay function: Introduce a new top-level function that serves as the single entry point for all overlays:

OverlayCompleter<T> showOverlay<T>({
  required BuildContext context,
  required WidgetBuilder builder,
  required OverlayConfiguration overlay,
  bool adaptive = false,
});

5. Manage adaptiveness explicitly: The OverlayConfiguration will feature an adaptiveConversion(BuildContext context) method.

• When showOverlay is called with adaptive: true, it will first call adaptiveConversion on the provided overlay configuration.
• This allows a configuration (e.g. PopoverConfiguration) to intelligently return a different configuration (e.g. DrawerConfiguration) based on the platform or the context.
• This makes the "popover-to-drawer" behavior transparent, configurable, and overrideable for developers.

6. (Optional) Explicit conversions: Configurations can also expose manual conversion methods (e.g. PopoverConfiguration.toDrawer({OverlayPosition? position})) for developers who want granular control without relying on the adaptive flag.

Feature Type

Component Enhancement

Use Cases

no specific cases, but less headache for new developers

Alternatives Considered

No response

Priority

High - Important for my use case

Implementation Ideas

No response

Related Examples

No response

Checklist

• I have searched existing issues and this feature hasn't been requested
• I have provided clear use cases for this feature
• I understand this feature may take time to implement

[sunarya-thito]

As a follow-up on the implementation details:
This proposal is designed to be backwards-compatible, so no migration guide should be required. Existing overlay functions (showPopover, openDrawer, etc) will remain functional.

The primary change is that the default for adaptive popovers will be set to false. Developers who rely on popovers automatically converting to bottom drawers on mobile will need to explicitly opt-in by passing adaptive: true to the function, except for popup-based components, the option will be default to true unless set otherwise on the component constructor.

Additionally, any custom OverlayHandler configurations on OverlayManager or ShadcnApp will become obselete and can be safely removed.