@rdlabo/ionic-theme-ios27 1.2.0 → 1.2.1-beta.pr273.shae866fb1dca9f

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellVerticalBars.swift

@@ -7,6 +7,7 @@ protocol ShellVerticalBarsControlling: AnyObject {
     func attach(to owner: UIViewController, in parent: UIView)
     @MainActor func apply(_ controls: [ShellControl], rendering: ShellRendering, edge: String)
     var ownsKeyboardChrome: Bool { get }
+    func presentPopover(anchor: String, host: ShellOverlayHost, completion: @escaping (Bool) -> Void) -> Bool
     func detach()
 }
 
@@ -32,6 +33,9 @@ final class ShellVerticalBarsModel: ObservableObject {
         let slot: ShellControl.ToolbarSlot?
     }
 
+    @Published var popoverAnchor: String?
+    var popoverHost: ShellOverlayHost?
+    var popoverPresented: ((Bool) -> Void)?
     @Published var search: ShellVerticalSearchModel?
     @Published var back: Item?
     @Published var groups: [Group] = []
@@ -45,9 +49,11 @@ final class ShellVerticalBarsModel: ObservableObject {
     func apply(_ controls: [ShellControl], rendering: ShellRendering,
                now: CFAbsoluteTime = CFAbsoluteTimeGetCurrent()) {
         func item(_ source: ShellItem) -> Item {
-            Item(id: source.id, label: source.content.label,
+            let image = rendering.image(source.content)
+            return Item(id: source.id, label: source.content.label,
                  accessibilityLabel: source.content.accessibilityLabel,
-                 image: rendering.image(source.content),
+                 // UIKit toolbar extraction uses the UIImage's rendering mode.
+                 image: source.content.disabled ? image?.withRenderingMode(.alwaysTemplate) : image,
                  clear: source.content.buttonFill == .clear,
                  background: source.content.backgroundColor.map { Color(uiColor: rendering.color($0)) },
                  borderColor: source.content.borderColor.map { Color(uiColor: rendering.color($0)) },
@@ -127,6 +133,13 @@ private func verticalBarsButton(_ item: ShellVerticalBarsModel.Item, model: Shel
     }
 }
 
+@available(iOS 26.0, *)
+private struct ShellVerticalPopoverContent: UIViewControllerRepresentable {
+    let host: ShellOverlayHost
+    func makeUIViewController(context: Context) -> ShellOverlayHost { host }
+    func updateUIViewController(_ controller: ShellOverlayHost, context: Context) {}
+}
+
 @available(iOS 26.0, *)
 private struct ShellVerticalBarsButton: ToolbarContent {
     @ObservedObject var model: ShellVerticalBarsModel
@@ -136,7 +149,40 @@ private struct ShellVerticalBarsButton: ToolbarContent {
     // Observe here so same-ID updates also refresh the shared toolbar background.
     var body: some ToolbarContent {
         if let item = model.groups.lazy.flatMap(\.items).first(where: { $0.id == id }) {
-            ToolbarItem(placement: placement) { verticalBarsButton(item, model: model) }
+            ToolbarItem(placement: placement) {
+                verticalBarsButton(item, model: model)
+                    .popover(isPresented: Binding(
+                        get: { model.popoverAnchor == item.id },
+                        set: { shown in
+                            if !shown && model.popoverAnchor == item.id {
+                                model.popoverAnchor = nil
+                                model.popoverHost?.event("dismiss")
+                            }
+                        }
+                    )) {
+                        if let host = model.popoverHost {
+                            ShellVerticalPopoverContent(host: host)
+                                .frame(width: host.preferredContentSize.width, height: host.preferredContentSize.height)
+                                .preferredColorScheme(host.options?["dark"] as? Bool == true ? .dark : .light)
+                                .presentationCompactAdaptation(.popover)
+                                .interactiveDismissDisabled(host.options?["backdropDismiss"] as? Bool == false)
+                                .onAppear {
+                                    guard model.popoverHost === host else { return }
+                                    host.anchoredVisible = true
+                                    let completion = model.popoverPresented
+                                    model.popoverPresented = nil
+                                    completion?(true)
+                                }
+                                .onDisappear {
+                                    host.anchoredVisible = false
+                                    let completion = host.anchoredDidDismiss
+                                    host.anchoredDidDismiss = nil
+                                    if model.popoverHost === host { model.popoverHost = nil }
+                                    completion?()
+                                }
+                        }
+                    }
+            }
                 .sharedBackgroundVisibility(item.clear ? .hidden : .automatic)
         }
     }
@@ -424,6 +470,36 @@ final class ShellVerticalBarsController: ShellVerticalBarsControlling {
         controller.overrideUserInterfaceStyle = controls.contains(where: \.dark) ? .dark : .light
     }
 
+    func presentPopover(anchor: String, host: ShellOverlayHost, completion: @escaping (Bool) -> Void) -> Bool {
+        guard container.window != nil, model.popoverAnchor == nil,
+              model.groups.flatMap(\.items).contains(where: { $0.id == anchor && !$0.disabled }) else { return false }
+        model.popoverHost = host
+        model.popoverPresented = completion
+        host.anchoredVisible = false
+        host.dismissAnchored = { [weak self, weak host] in
+            guard let self, let host, self.model.popoverHost === host else { return }
+            // A backdrop tap clears the binding before SwiftUI finishes closing.
+            // Keep the live content and completion until onDisappear, including
+            // when dismissal has already started through the system binding.
+            if self.model.popoverAnchor != nil {
+                var transaction = Transaction()
+                transaction.disablesAnimations = host.options?["animated"] as? Bool == false
+                withTransaction(transaction) { self.model.popoverAnchor = nil }
+            }
+            // Before onAppear there will be no onDisappear to finish cleanup.
+            if !host.anchoredVisible {
+                let completion = self.model.popoverPresented
+                self.model.popoverPresented = nil
+                self.model.popoverHost = nil
+                completion?(false)
+            }
+        }
+        var transaction = Transaction()
+        transaction.disablesAnimations = host.options?["animated"] as? Bool == false
+        withTransaction(transaction) { model.popoverAnchor = anchor }
+        return true
+    }
+
     func detach() {
         guard controller.parent != nil else { return }
         controller.willMove(toParent: nil)

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -10,8 +10,14 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "getWebViewMetrics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "update", returnType: CAPPluginReturnPromise),
-        CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise)
+        CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "prepareOverlay", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "presentOverlay", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "dismissOverlay", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "closeOverlay", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "stopOverlays", returnType: CAPPluginReturnPromise)
     ]
+    private var overlays: ShellOverlayController?
     private var host: ShellHost?
     private var verticalBars: ShellVerticalBarsControlling?
     private var controls: [String: UIView] = [:]
@@ -74,6 +80,56 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         observers.forEach(NotificationCenter.default.removeObserver)
     }
 
+    @objc func prepareOverlay(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self, let id = call.getString("id"),
+                  let source = self.bridge?.webView, let owner = self.bridge?.viewController else {
+                call.reject("Popover source unavailable"); return
+            }
+            if self.overlays == nil {
+                self.overlays = ShellOverlayController(source: source, owner: owner) { [weak self] id, action in
+                    self?.notifyListeners("overlay", data: ["id": id, "action": action])
+                }
+            }
+            guard self.overlays?.prepare(id) == true else { call.reject("Popover already pending"); return }
+            call.resolve()
+        }
+    }
+
+    @objc func presentOverlay(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self, let overlays = self.overlays, let id = call.getString("id") else {
+                call.reject("Popover not prepared"); return
+            }
+            overlays.present(id, options: call.getObject("presentation"), anchored: { [weak self] anchor, host, completion in
+                self?.verticalBars?.presentPopover(anchor: anchor, host: host, completion: completion) ?? false
+            }) { presented in
+                if presented { call.resolve() } else { call.reject("Native Vertical Bars anchor unavailable") }
+            }
+        }
+    }
+
+    @objc func dismissOverlay(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard let overlays = self?.overlays, let id = call.getString("id") else { call.resolve(); return }
+            overlays.dismiss(id, animated: call.getBool("animated") ?? false) { call.resolve() }
+        }
+    }
+
+    @objc func closeOverlay(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard let overlays = self?.overlays, let id = call.getString("id") else { call.resolve(); return }
+            overlays.close(id) { call.resolve() }
+        }
+    }
+
+    @objc func stopOverlays(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard let self, let overlays = self.overlays else { call.resolve(); return }
+            overlays.stop { self.overlays = nil; call.resolve() }
+        }
+    }
+
     private func webViewMetrics() -> JSObject? {
         guard #available(iOS 26.0, *), let webView = bridge?.webView else { return nil }
         webView.layoutIfNeeded()

package/ios/Sources/IonicNativeUIShellPlugin/Overlays/ShellOverlayController.swift

@@ -0,0 +1,116 @@
+import UIKit
+import WebKit
+
+/// Intercepts only a prepared blank window. Other requests keep Capacitor's behavior.
+final class ShellOverlayController: NSObject, WKUIDelegate {
+    private weak var source: WKWebView?
+    private weak var owner: UIViewController?
+    private let original: WKUIDelegate?
+    private let automaticallyOpensWindows: Bool
+    private var prepared: String?
+    private let event: (String, String) -> Void
+    private var id: String?
+    private var host: ShellOverlayHost?
+
+    init(source: WKWebView, owner: UIViewController, event: @escaping (String, String) -> Void) {
+        self.source = source
+        self.owner = owner
+        self.event = event
+        original = source.uiDelegate
+        automaticallyOpensWindows = source.configuration.preferences.javaScriptCanOpenWindowsAutomatically
+        super.init()
+        source.uiDelegate = self
+    }
+
+    override func responds(to selector: Selector!) -> Bool {
+        super.responds(to: selector) || original?.responds(to: selector) == true
+    }
+
+    override func forwardingTarget(for selector: Selector!) -> Any? {
+        original?.responds(to: selector) == true ? original : super.forwardingTarget(for: selector)
+    }
+
+    func prepare(_ id: String) -> Bool {
+        guard prepared == nil, host == nil else { return false }
+        prepared = id
+        source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = true
+        return true
+    }
+
+    func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
+                 for navigationAction: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
+        // WebKit percent-encodes '#' inside about: URLs; compare the decoded form.
+        guard webView === source, navigationAction.sourceFrame.isMainFrame,
+              let prepared, navigationAction.targetFrame == nil,
+              navigationAction.request.url?.absoluteString.removingPercentEncoding == "about:blank#\(prepared)" else {
+            return original?.webView?(webView, createWebViewWith: configuration,
+                                      for: navigationAction, windowFeatures: windowFeatures)
+        }
+        self.prepared = nil
+        source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+        id = prepared
+        let host = ShellOverlayHost(configuration: configuration, options: nil) { [weak self] action in
+            self?.event(prepared, action)
+        }
+        host.webView.uiDelegate = self
+        host.webView.frame = source?.bounds ?? .zero
+        self.host = host
+        return host.webView
+    }
+
+    func present(_ id: String, options: [String: Any]?, anchored: (String, ShellOverlayHost, @escaping (Bool) -> Void) -> Bool,
+                 completion: @escaping (Bool) -> Void) {
+        guard self.id == id, let host, let owner,
+              owner.presentedViewController == nil else { completion(false); return }
+        host.apply(options)
+        if host.options?["kind"] as? String == "popover",
+           let anchor = host.options?["anchorId"] as? String,
+           anchored(anchor, host, completion) { return }
+        completion(false)
+    }
+
+    // Keep the WebView alive until JavaScript has restored the adopted nodes and listeners.
+    func dismiss(_ id: String, animated: Bool, completion: @escaping () -> Void) {
+        guard self.id == id, let host else { completion(); return }
+        if let dismiss = host.dismissAnchored {
+            if host.anchoredVisible { host.anchoredDidDismiss = completion; dismiss() }
+            else { dismiss(); completion() }
+            return
+        }
+        guard host.presentingViewController != nil else { completion(); return }
+        host.dismiss(animated: animated, completion: completion)
+    }
+
+    func close(_ id: String, completion: @escaping () -> Void) {
+        if prepared == id {
+            prepared = nil
+            source?.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+        }
+        guard self.id == id, let host else { completion(); return }
+        let finish = { [self] in
+            host.webView.uiDelegate = nil
+            self.host = nil
+            self.id = nil
+            completion()
+        }
+        if let dismiss = host.dismissAnchored {
+            if host.anchoredVisible { host.anchoredDidDismiss = finish; dismiss() }
+            else { dismiss(); finish() }
+        }
+        else if host.presentingViewController == nil { finish() }
+        else { host.dismiss(animated: false, completion: finish) }
+    }
+
+    func stop(completion: @escaping () -> Void) {
+        let finish = { [self] in
+            prepared = nil
+            if let source, source.uiDelegate === self {
+                source.uiDelegate = original
+                source.configuration.preferences.javaScriptCanOpenWindowsAutomatically = automaticallyOpensWindows
+            }
+            completion()
+        }
+        if let id { close(id, completion: finish) }
+        else { finish() }
+    }
+}

package/ios/Sources/IonicNativeUIShellPlugin/Overlays/ShellOverlayHost.swift

@@ -0,0 +1,36 @@
+import UIKit
+import WebKit
+
+/// Hosts only the live content of a Vertical Bars popover.
+final class ShellOverlayHost: UIViewController {
+    let webView: WKWebView
+    private(set) var options: [String: Any]?
+    let event: (String) -> Void
+    var dismissAnchored: (() -> Void)?
+    var anchoredVisible = false
+    var anchoredDidDismiss: (() -> Void)?
+
+    init(configuration: WKWebViewConfiguration, options: [String: Any]?, event: @escaping (String) -> Void) {
+        webView = WKWebView(frame: .zero, configuration: configuration)
+        self.event = event
+        super.init(nibName: nil, bundle: nil)
+        apply(options)
+    }
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    func apply(_ options: [String: Any]?) {
+        guard let options else { return }
+        self.options = options
+        preferredContentSize = CGSize(width: options["width"] as? Double ?? 280, height: options["height"] as? Double ?? 200)
+        overrideUserInterfaceStyle = options["dark"] as? Bool == true ? .dark : .light
+    }
+
+    override func loadView() {
+        webView.isOpaque = false
+        webView.backgroundColor = .clear
+        webView.scrollView.backgroundColor = .clear
+        webView.scrollView.contentInsetAdjustmentBehavior = .never
+        view = webView
+        view.accessibilityViewIsModal = true
+    }
+}

package/ios/Tests/IonicNativeUIShellPluginTests/ShellSnapshotTests.swift

@@ -1,8 +1,35 @@
 import XCTest
+import WebKit
 import Capacitor
 @testable import IonicNativeUIShellPlugin
 
 final class ShellSnapshotTests: XCTestCase {
+    @MainActor func testVerticalPopoverCanCancelBeforeSwiftUIAppearsAndReopen() throws {
+        guard #available(iOS 26.0, *) else { throw XCTSkip("Requires native Vertical Bars") }
+        let owner = UIViewController()
+        let window = UIWindow(frame: CGRect(x: 0, y: 0, width: 700, height: 900))
+        window.rootViewController = owner
+        window.makeKeyAndVisible()
+        defer { window.isHidden = true }
+        let rail = ShellVerticalBarsController(activate: { _ in }, changed: { _, _, _, _, _ in 0 })
+        rail.attach(to: owner, in: owner.view)
+        defer { rail.detach() }
+        rail.apply(try decode([control(["placement": "vertical-bars"])]).controls,
+                   rendering: ShellRendering(), edge: "right")
+        for _ in 0..<3 {
+            let host = ShellOverlayHost(configuration: WKWebViewConfiguration(), options: nil, event: { _ in })
+            var results: [Bool] = []
+            XCTAssertTrue(rail.presentPopover(anchor: "action", host: host, completion: { results.append($0) }))
+            // Cancel in the same runloop turn, before SwiftUI can call onAppear.
+            XCTAssertFalse(host.anchoredVisible)
+            host.dismissAnchored?()
+            XCTAssertEqual(results, [false])
+            XCTAssertFalse(host.anchoredVisible)
+            host.dismissAnchored?()
+            XCTAssertEqual(results, [false], "Cancellation must settle presentation only once")
+        }
+    }
+
     private func item(_ changes: JSObject = [:]) -> JSObject {
         var value: JSObject = ["id": "action", "x": 4.0, "y": 8.0, "width": 44.0, "height": 44.0,
             "label": "Send", "accessibilityLabel": "Send message", "disabled": false, "selected": false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "1.2.0",
+  "version": "1.2.1-beta.pr273.shae866fb1dca9f",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -61,7 +61,7 @@
   },
   "homepage": "https://docs.rdlabo.dev/projects/ionic-theme-ios27",
   "dependencies": {
-    "@rdlabo/ionic-theme-utils": "0.1.2"
+    "@rdlabo/ionic-theme-utils": "0.1.4"
   },
   "devDependencies": {
     "@capacitor/core": "^8.5.2",

package/src/native/components/index.ts

@@ -6,7 +6,7 @@ import * as menuButton from './ion-menu-button';
 import * as tabBar from './ion-tab-bar';
 import * as segment from './ion-segment';
 import * as fab from './ion-fab';
-import { isDisabledButtonGroupChild, isVerticalBarsSource, visible } from '../shared/dom';
+import { isDisabledButtonGroupChild, isVerticalBarsSource, visible, withoutPrehide } from '../shared/dom';
 import type { Candidate, Identify } from '../shared/candidate';
 
 // Static composition only. Each component declares its own tag, discovery and reader.
@@ -48,5 +48,6 @@ export const readCandidate = (element: HTMLElement, id: Identify, options: Verti
   )
     return;
   if (element.contains(element.ownerDocument.activeElement)) return;
-  return components.find((component) => component.tag === element.localName)?.read(element, id, options);
+  // Read icon and control geometry before restoring prehide, which can collapse the toolbar.
+  return withoutPrehide(element, () => components.find((component) => component.tag === element.localName)?.read(element, id, options));
 };

package/src/native/definitions.ts

@@ -11,6 +11,8 @@ export interface NativeUIShellStatus {
 }
 
 export interface VerticalControlAreaOptions {
+  /** Opt-in popovers anchored to native Vertical Bars buttons. */
+  controls?: Pick<NativeUIShellControls, 'popover'>;
   /** Appearance of native vertical ion-button and ion-menu-button actions.
    * `system` (default) uses SwiftUI styling and template icons; `source` projects supported Ionic fill and colors.
    * Local data-projection="source|system" or ios-theme-projection-source / ios-theme-projection-system take precedence:
@@ -32,7 +34,7 @@ export interface VerticalControlAreaOptions {
 export interface NativeUIShellOptions extends VerticalControlAreaOptions {
   /** Enables Native UI Shell globally. Defaults to `true`. */
   enabled?: boolean;
-  /** Controls eligible for native projection. Omit to enable every control; when present, only `true` controls are enabled. */
+  /** Controls eligible for native projection. Omit to enable tabs, toolbar, segment and fab; popover always requires explicit opt-in. When present, only `true` controls are enabled. */
   controls?: NativeUIShellControls;
   /** Internal: limit native projection to the Vertical Control Area. */
   verticalBarsOnly?: boolean;
@@ -47,6 +49,8 @@ export interface NativeUIShellControls {
   segment?: boolean;
   /** Projects floating action buttons. */
   fab?: boolean;
+  /** Relays popovers anchored to native Vertical Bars buttons. Defaults to false. */
+  popover?: boolean;
 }
 
 export interface NativeUIShellHandle {
@@ -183,9 +187,31 @@ export interface WebViewMetrics {
 export interface NativeUIShellPlugin {
   configure(options?: { verticalBarsOnly?: boolean }): Promise<{ supported: boolean }>;
   getWebViewMetrics(): Promise<WebViewMetrics>;
+  prepareOverlay(options: { id: string }): Promise<void>;
+  presentOverlay(options: { id: string; presentation?: ShellPopoverPresentation }): Promise<void>;
+  dismissOverlay(options: { id: string; animated: boolean }): Promise<void>;
+  closeOverlay(options: { id: string }): Promise<void>;
+  stopOverlays(): Promise<void>;
   update(snapshot: ShellSnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
   clear(options: { revision: number }): Promise<void>;
   addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
   addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
   addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'overlay', listener: (event: ShellOverlayEvent) => void): Promise<PluginListenerHandle>;
+}
+
+export interface ShellPopoverPresentation {
+  kind: 'popover';
+  animated: boolean;
+  dark: boolean;
+  anchorId: string;
+  width: number;
+  height: number;
+  backgroundColor: string;
+  backdropDismiss: boolean;
+}
+
+export interface ShellOverlayEvent {
+  id: string;
+  action: 'dismiss';
 }

package/src/native/index.ts

@@ -11,6 +11,7 @@ import type {
   WebViewMetrics,
 } from './definitions';
 import { createRuntime } from './runtime';
+import { createOverlayController } from './overlays/controller';
 import { createVerticalBarsWebProjection } from './vertical-bars-web';
 import { prehideVerticalBarsToolbarSources } from './prehide';
 import { observeVerticalBarsModals } from './shared/modal';
@@ -64,7 +65,7 @@ const manage = (
   handle: NativeUIShellHandle,
   lifecycle: {
     reason?: string;
-    suspend?: () => (() => void) | undefined;
+    suspend?: () => (() => void) | undefined | Promise<(() => void) | undefined>;
     /** Runs after teardown; clears the shared slot only while this activation owns it. */
     release?: () => void;
     destroy?: () => void | Promise<void>;
@@ -75,7 +76,7 @@ const manage = (
     getStatus: () => (lifecycle.reason ? { ...handle.getStatus(), reason: lifecycle.reason } : handle.getStatus()),
     async suspend() {
       const lease = await handle.suspend();
-      const resume = lifecycle.suspend?.();
+      const resume = await lifecycle.suspend?.();
       return {
         async resume() {
           await lease.resume();
@@ -89,8 +90,11 @@ const manage = (
       try {
         await handle.destroy();
       } finally {
-        await lifecycle.destroy?.();
-        lifecycle.release?.();
+        try {
+          await lifecycle.destroy?.();
+        } finally {
+          lifecycle.release?.();
+        }
       }
     },
   };
@@ -171,7 +175,7 @@ export const enableVerticalControlArea = async (options: VerticalControlAreaOpti
   const handle = await enableNativeUIShell({
     buttonProjection: options.buttonProjection,
     buttonDefaultFill: options.buttonDefaultFill,
-    controls: { tabs: true, toolbar: true },
+    controls: { tabs: true, toolbar: true, popover: options.controls?.popover === true },
     verticalBarsOnly: true,
   });
   return {
@@ -203,6 +207,7 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
     // Local source overrides can use this even when the startup projection is system.
     options.buttonDefaultFill ?? null,
     ...(['tabs', 'toolbar', 'segment', 'fab'] as const).map((component) => !controls || controls[component] === true),
+    controls?.popover === true,
   ]);
   if (active && activeConfiguration !== configuration)
     return Promise.reject(
@@ -235,6 +240,7 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
     (async () => {
       if (Capacitor.getPlatform() !== 'ios') return fallback('Requires Capacitor iOS');
       let runtime: NativeUIShellHandle | undefined;
+      let overlays: Awaited<ReturnType<typeof createOverlayController>> | undefined;
       let metricsListener: Awaited<ReturnType<typeof plugin.addListener>> | undefined;
       let stopVerticalBarsLayout: (() => void) | undefined;
       try {
@@ -261,10 +267,20 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
           native,
           createVerticalBarsWebProjection(document, options, () => !nativeVerticalBars() || native.getStatus().state === 'stopped'),
         );
+        if (controls?.popover === true)
+          overlays = await createOverlayController(document, plugin, options, native.retain, nativeVerticalBars);
         return manage(runtime, {
-          suspend: () => prehide?.suspend(),
+          suspend: async () => {
+            const restorePrehide = prehide?.suspend();
+            const resumeOverlays = await overlays?.suspend();
+            return () => {
+              restorePrehide?.();
+              resumeOverlays?.();
+            };
+          },
           release,
           destroy: async () => {
+            await overlays?.destroy();
             await metricsListener?.remove().catch(() => {});
             stopVerticalBarsLayout?.();
             prehide?.stop();
@@ -272,6 +288,7 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
           },
         });
       } catch (error) {
+        await overlays?.destroy();
         await runtime?.destroy();
         await metricsListener?.remove().catch(() => {});
         stopVerticalBarsLayout?.();

package/src/native/overlays/content.ts

@@ -0,0 +1,51 @@
+import { sheetText } from './styles';
+
+/** Constructed stylesheets cannot cross documents with their nodes. */
+export const moveContent = (content: HTMLElement[], destination: HTMLElement): (() => void) => {
+  const home = content.map((element) => ({ element, parent: element.parentNode!, next: element.nextSibling }));
+  const roots: { root: ShadowRoot; css: string; sheets: CSSStyleSheet[] }[] = [];
+  const collect = (node: Element) => {
+    if (node.shadowRoot) {
+      roots.push({
+        root: node.shadowRoot,
+        css: sheetText(node.shadowRoot.adoptedStyleSheets),
+        sheets: [...node.shadowRoot.adoptedStyleSheets],
+      });
+      for (const child of Array.from(node.shadowRoot.children)) collect(child);
+    }
+    for (const child of Array.from(node.children)) collect(child);
+  };
+  content.forEach(collect);
+  for (const element of content) destination.append(destination.ownerDocument.adoptNode(element));
+  const styles = roots
+    .filter(({ css }) => css)
+    .map(({ root, css }) => {
+      const style = destination.ownerDocument.createElement('style');
+      style.textContent = css;
+      root.append(style);
+      return style;
+    });
+  return () => {
+    styles.forEach((style) => style.remove());
+    for (const { element, parent, next } of home) {
+      const connected = element.isConnected;
+      parent.ownerDocument!.adoptNode(element);
+      // Ionic may already have destroyed the Angular component on dismiss.
+      if (connected) parent.insertBefore(element, next?.parentNode === parent ? next : null);
+    }
+    for (const { root, css, sheets } of roots) {
+      // WebKit re-associates adopted sheets with the new document across
+      // adoptNode, so they may no longer match this root; fall back to the
+      // inline copy instead of aborting the remaining restore.
+      try {
+        root.adoptedStyleSheets = sheets;
+      } catch {
+        if (css) {
+          const style = root.ownerDocument.createElement('style');
+          style.textContent = css;
+          root.append(style);
+        }
+      }
+    }
+  };
+};