@rdlabo/ionic-theme-ios27 1.2.0-0 → 1.2.0-2

package/src/native/index.ts

@@ -12,6 +12,7 @@ import type {
 import { createRuntime } from './runtime';
 import { createVerticalBarsWebProjection } from './vertical-bars-web';
 import { prehideVerticalBarsToolbarSources } from './prehide';
+import { observeVerticalBarsModals } from './shared/modal';
 export type {
   NativeUIShellComponent,
   NativeUIShellControls,
@@ -19,13 +20,11 @@ export type {
   NativeUIShellOptions,
   NativeUIShellStatus,
   NativeUIShellSuspension,
-  DeviceLayout,
   VerticalBarEdge,
   VerticalBarPlacement,
   VerticalControlAreaHandle,
   WebViewMetrics,
 } from './definitions';
-export { HingeStatus } from './definitions';
 
 const plugin = registerPlugin<NativeUIShellPlugin>('IonicNativeUIShell');
 export const IonicNativeUIShell = plugin;
@@ -97,8 +96,7 @@ const manage = (
 
 /** Reads the current native WebView geometry and applies it to page transitions. */
 export const configureNativeTransition = async (): Promise<WebViewMetrics> => {
-  const metrics =
-    typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? (await plugin.getDeviceLayout()).webViewMetrics : { radius: 0 };
+  const metrics = typeof document !== 'undefined' && Capacitor.getPlatform() === 'ios' ? await plugin.getWebViewMetrics() : { radius: 0 };
   setConfig({ radius: metrics.radius });
   return metrics;
 };
@@ -109,6 +107,39 @@ const physicalVerticalBarEdge = (edge: Exclude<VerticalBarEdge, null>, rtl: bool
 
 const elementRtl = (element: Element): boolean => element.closest('[dir]')?.getAttribute('dir') === 'rtl';
 
+// Device facts are supplied by the application; the theme only compares placement.
+const nativePlacements = new WeakMap<HTMLElement, { edge: VerticalBarEdge; rtl?: boolean }>();
+const horizontalFallbackAttribute = 'data-native-ui-shell-vertical-bars-suspended';
+
+// Keep the requested rail while ordinary Native UI Shell temporarily uses its
+// horizontal layout. Removing the effective class restores normal measurements,
+// toolbar ownership and safe areas throughout the existing rendering pipeline.
+const observeNativeVerticalBarsLayout = (doc: Document): (() => void) => {
+  const reconcile = () => {
+    const app = doc.querySelector<HTMLElement>('ion-app');
+    if (!app) return;
+    const requested = app.classList.contains('ios-theme-vertical-bars') || app.hasAttribute(horizontalFallbackAttribute);
+    const suspended = requested && nativePlacements.get(app)?.edge == null;
+    if (app.hasAttribute(horizontalFallbackAttribute) !== suspended) app.toggleAttribute(horizontalFallbackAttribute, suspended);
+    if (app.classList.contains('ios-theme-vertical-bars') !== (requested && !suspended)) {
+      app.classList.toggle('ios-theme-vertical-bars', requested && !suspended);
+    }
+  };
+  const observer = new MutationObserver(reconcile);
+  observer.observe(doc.documentElement, { childList: true, subtree: true, attributes: true, attributeFilter: ['class'] });
+  doc.defaultView?.addEventListener('nativeUIShellRefresh', reconcile);
+  reconcile();
+  return () => {
+    observer.disconnect();
+    doc.defaultView?.removeEventListener('nativeUIShellRefresh', reconcile);
+    const app = doc.querySelector<HTMLElement>(`ion-app[${horizontalFallbackAttribute}]`);
+    if (app) {
+      app.removeAttribute(horizontalFallbackAttribute);
+      app.classList.add('ios-theme-vertical-bars');
+    }
+  };
+};
+
 /**
  * Applies one placement to the CSS layout and both Web/native projections.
  * Pass `rtl` when the document direction is known; otherwise the nearest `dir` attribute is used.
@@ -117,11 +148,16 @@ export const setVerticalControlAreaPlacement = (placement: VerticalBarEdge | Ver
   if (typeof document === 'undefined') return;
   const app = document.querySelector<HTMLElement>('ion-app');
   if (!app) throw new Error('Vertical Control Area requires ion-app');
-  const { edge, inset } = placement && typeof placement === 'object' ? placement : { edge: placement, inset: 0 };
+  const { edge, inset = 0 } = placement && typeof placement === 'object' ? placement : { edge: placement, inset: 0 };
+  if (placement && typeof placement === 'object' && placement.nativeEdge !== undefined) {
+    nativePlacements.set(app, { edge: placement.nativeEdge, rtl });
+  }
+  app.removeAttribute(horizontalFallbackAttribute);
   app.classList.toggle('ios-theme-vertical-bars', edge !== null);
   app.classList.toggle('ios-theme-vertical-bars-left', edge !== null && physicalVerticalBarEdge(edge, rtl ?? elementRtl(app)) === 'left');
   if (edge && Number.isFinite(inset) && inset > 0) app.style.setProperty('--ios-theme-vertical-bars-native-inset', `${inset}px`);
   else app.style.removeProperty('--ios-theme-vertical-bars-native-inset');
+  document.defaultView?.dispatchEvent(new Event('nativeUIShellRefresh'));
 };
 
 /** Call once at application startup. Ionic markup remains the source of truth. */
@@ -160,6 +196,7 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
     );
   if (active) return active;
   activeConfiguration = configuration;
+  const stopModals = observeVerticalBarsModals(document);
   const prehide =
     options.controls === undefined || options.controls.toolbar === true ? prehideVerticalBarsToolbarSources(document) : undefined;
   // A slow destroy of a superseded activation must not release a newer one.
@@ -174,38 +211,37 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
     manage(createVerticalBarsWebProjection(document, options), {
       reason,
       suspend: () => prehide?.suspend(),
-      destroy: () => prehide?.stop(),
+      destroy: () => {
+        prehide?.stop();
+        stopModals();
+      },
       release,
     });
   return (start = active =
     (async () => {
       if (Capacitor.getPlatform() !== 'ios') return fallback('Requires Capacitor iOS');
       let runtime: NativeUIShellHandle | undefined;
-      let placementListener: Awaited<ReturnType<typeof plugin.addListener>> | undefined;
-      let monitoring = false;
+      let metricsListener: Awaited<ReturnType<typeof plugin.addListener>> | undefined;
+      let stopVerticalBarsLayout: (() => void) | undefined;
       try {
-        if (!options.verticalBarsOnly) await configureNativeTransition().catch(() => undefined);
         const capabilities = await plugin.configure({ verticalBarsOnly: options.verticalBarsOnly === true });
         if (!capabilities.supported) return fallback('Requires iOS 26 or later');
-        let nativeEdge: VerticalBarEdge = null;
+        if (!options.verticalBarsOnly) stopVerticalBarsLayout = observeNativeVerticalBarsLayout(document);
+        // The application owns device state and selects the rail through placement classes.
         const nativeVerticalBars = () => {
-          const root = document.querySelector('ion-app.ios-theme-vertical-bars');
-          if (!root) return false;
-          // The trait stays unspecified when the OS cannot report a rail — for
-          // example an app linked against an SDK older than 27.1 — so the DOM
-          // class is trusted there. When the OS does report an edge, the native
-          // rail only takes over once the app has applied the matching class.
-          const domEdge = root.classList.contains('ios-theme-vertical-bars-left') ? 'left' : 'right';
-          return nativeEdge === null || physicalVerticalBarEdge(nativeEdge, elementRtl(root)) === domEdge;
+          const app = document.querySelector<HTMLElement>('ion-app.ios-theme-vertical-bars');
+          if (!app) return false;
+          const reported = nativePlacements.get(app);
+          if (!reported?.edge) return false;
+          const physicalEdge = app.classList.contains('ios-theme-vertical-bars-left') ? 'left' : 'right';
+          return physicalEdge === physicalVerticalBarEdge(reported.edge, reported.rtl ?? elementRtl(app));
         };
-        await plugin.startDeviceLayoutMonitoring();
-        monitoring = true;
-        placementListener = await plugin.addListener('deviceLayoutChange', ({ placement, webViewMetrics }) => {
-          nativeEdge = placement.edge;
-          if (!options.verticalBarsOnly) setConfig({ radius: webViewMetrics.radius });
-          document.defaultView?.dispatchEvent(new Event('nativeUIShellRefresh'));
-        });
-        nativeEdge = (await plugin.getDeviceLayout()).placement.edge;
+        if (!options.verticalBarsOnly) {
+          metricsListener = await plugin.addListener('webViewMetricsChange', (metrics) => {
+            setConfig({ radius: metrics.radius });
+          });
+          await configureNativeTransition().catch(() => undefined);
+        }
         const native = await createRuntime(document, plugin, options, nativeVerticalBars, options.verticalBarsOnly === true);
         runtime = combine(
           native,
@@ -215,15 +251,16 @@ export const enableNativeUIShell = (options: NativeUIShellOptions = {}): Promise
           suspend: () => prehide?.suspend(),
           release,
           destroy: async () => {
-            await placementListener?.remove().catch(() => {});
-            if (monitoring) await plugin.stopDeviceLayoutMonitoring().catch(() => {});
+            await metricsListener?.remove().catch(() => {});
+            stopVerticalBarsLayout?.();
             prehide?.stop();
+            stopModals();
           },
         });
       } catch (error) {
         await runtime?.destroy();
-        await placementListener?.remove().catch(() => {});
-        if (monitoring) await plugin.stopDeviceLayoutMonitoring().catch(() => {});
+        await metricsListener?.remove().catch(() => {});
+        stopVerticalBarsLayout?.();
         return fallback(error instanceof Error ? error.message : String(error));
       }
     })());

package/src/native/prehide.ts

@@ -1,3 +1,4 @@
+import { modalUsesVerticalBars } from './shared/modal';
 import { LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE, LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE } from '@ionic/core';
 import { VERTICAL_BARS_TRANSITION_CANCELED } from '../native-integration';
 import {
@@ -17,7 +18,7 @@ import {
   setVerticalBarsPlacement,
 } from './shared/dom';
 
-const overlays = 'ion-menu, ion-modal, ion-popover';
+const overlays = 'ion-menu, ion-popover';
 const sourceSelector = 'ion-back-button, ion-menu-button, ion-buttons, ion-button';
 // Realm- and teardown-safe: globals such as Element/HTMLElement may be gone
 // when a queued mutation microtask or a stale listener still runs.
@@ -60,7 +61,7 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     scopes.delete(scope);
   };
   const capture = (scope: HTMLElement) => {
-    if (!root()?.contains(scope) || scope.closest(overlays) || verticalBarsPages.isDeparted(scope)) return;
+    if (!root()?.contains(scope) || scope.closest(overlays) || !modalUsesVerticalBars(scope) || verticalBarsPages.isDeparted(scope)) return;
     const owned = scopes.get(scope) ?? new Set<HTMLElement>();
     const place = (element: HTMLElement, rail: boolean) => {
       if (owned.has(element)) return;
@@ -73,7 +74,8 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
     };
     const sources = scope.matches('ion-back-button') ? [scope] : Array.from(scope.querySelectorAll<HTMLElement>(sourceSelector));
     sources.forEach((element) => {
-      if (element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope)) return;
+      if (!modalUsesVerticalBars(element) || element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope))
+        return;
       if (element.matches('ion-buttons')) {
         const children = childElements(element);
         const actions = children.filter((child) => eligible(child) && isVerticalBarsToolbarActionShape(child));
@@ -134,7 +136,7 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
       Array.from(scopes.keys()).forEach(release);
       return;
     }
-    for (const scope of scopes.keys()) if (!scope.isConnected) release(scope);
+    for (const scope of scopes.keys()) if (!scope.isConnected || !modalUsesVerticalBars(scope)) release(scope);
     for (const [element, pending] of pendingBacks) if (element.shadowRoot || element.classList.contains('hydrated')) capture(pending.scope);
     // Ionic inserts the destination as invisible before WillEnter. Hide its
     // sources in that same mutation microtask; capture new DOM identities on active pages too.
@@ -193,6 +195,7 @@ export const prehideVerticalBarsToolbarSources = (doc: Document): { suspend: ()
   for (const name of [LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE])
     doc.addEventListener(name, onPageLifecycle, { capture: true, signal: listeners.signal });
   doc.addEventListener(VERTICAL_BARS_TRANSITION_CANCELED, onTransitionCanceled, { capture: true, signal: listeners.signal });
+  doc.defaultView?.addEventListener('nativeUIShellRefresh', reconcile, { signal: listeners.signal });
   reconcile();
   const mutationRelevant = (record: MutationRecord) => {
     if (record.type === 'childList')

package/src/native/runtime.ts

@@ -1,3 +1,4 @@
+import { inVerticalBarsSurface, topModal, modalUsesVerticalBars, modalVerticalBarFrame } from './shared/modal';
 import type { PluginListenerHandle } from '@capacitor/core';
 import { LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE } from '@ionic/core';
 import { VERTICAL_BARS_TRANSITION_CANCELED, getNativeSearchBindings, setNativeUIShellIntegration } from '../native-integration';
@@ -126,7 +127,7 @@ export const createRuntime = async (
     lastSnapshot = '';
     search.release(element);
     element.removeAttribute(marker);
-    if (!stopped) crossfade.play(element, false, handoffInstant || isVerticalBarsSource(element));
+    if (!stopped) crossfade.play(element, false, isVerticalBarsSource(element) ? !element.matches('ion-tab-bar') : handoffInstant);
     if (element.getAttribute('aria-hidden') === 'true') {
       const previous = sources.get(element);
       if (previous == null) element.removeAttribute('aria-hidden');
@@ -205,14 +206,19 @@ export const createRuntime = async (
         Array.from(pages).some((scope) => scope.contains(element)) ||
         Array.from(moving.keys()).some((surface) => surface.contains(element))));
   const painted = () => new Promise<void>((resolve) => win.requestAnimationFrame(() => win.requestAnimationFrame(() => resolve())));
-  const overlayOpen = (includeMenu = true) => {
+  const overlayOpen = (includeMenu = true, allowModal = false) => {
+    const modal = topModal(doc);
+    const ignored = (element: Element) => allowModal && !!modal && modalUsesVerticalBars(modal) && element.matches('ion-modal');
     for (const element of presented) if (!element.isConnected) presented.delete(element);
-    const presentedOverlayOpen = Array.from(presented).some((element) => includeMenu || !element.matches('ion-menu'));
+    const presentedOverlayOpen = Array.from(presented).some(
+      (element) => !ignored(element) && (includeMenu || !element.matches('ion-menu')),
+    );
     return (
       manualSuspensions.size > 0 ||
       presentedOverlayOpen ||
       Array.from(doc.querySelectorAll(overlays)).some(
         (element) =>
+          !ignored(element) &&
           (includeMenu || !element.matches('ion-menu')) &&
           ((element as Element & { presented?: boolean }).presented || element.classList.contains('show-menu')),
       )
@@ -225,7 +231,7 @@ export const createRuntime = async (
     search.keepSearchTabsVisible();
     for (const page of pages) if (!page.isConnected) pages.delete(page);
     for (const surface of moving.keys()) if (!surface.isConnected) moving.delete(surface);
-    if (doc.hidden || overlayOpen(false)) return [];
+    if (doc.hidden || overlayOpen(false, true)) return [];
     if (win.visualViewport && (win.visualViewport.scale !== 1 || win.visualViewport.offsetTop !== 0) && !search.hasActive()) return [];
     const menuOpen = overlayOpen();
     const candidates = unprojected(sources.keys(), () =>
@@ -233,7 +239,10 @@ export const createRuntime = async (
         .decorate(
           Array.from(doc.querySelectorAll<HTMLElement>(selector))
             .filter(
-              (element) => !verticalBarsPages.isDeparted(element) && (!blocked(element) || (menuOpen && isVerticalBarsSource(element))),
+              (element) =>
+                inVerticalBarsSurface(element) &&
+                !verticalBarsPages.isDeparted(element) &&
+                (!blocked(element) || (menuOpen && isVerticalBarsSource(element))),
             )
             .map(readEnabledCandidate)
             .filter((candidate): candidate is Candidate => !!candidate),
@@ -333,7 +342,14 @@ export const createRuntime = async (
           ? 'left'
           : 'right'
         : undefined;
-      const data = { viewportWidth: win.innerWidth, verticalBarEdge, controls: candidates.map((candidate) => candidate.control) };
+      const modal = topModal(doc);
+      const verticalBarFrame = modal && modalUsesVerticalBars(modal) ? modalVerticalBarFrame(modal) : undefined;
+      const data = {
+        verticalBarFrame,
+        viewportWidth: win.innerWidth,
+        verticalBarEdge,
+        controls: candidates.map((candidate) => candidate.control),
+      };
       const serialized = JSON.stringify(data);
       if (serialized === lastSnapshot && !forceRefresh) return;
       const snapshot: ShellSnapshot = { ...data, revision: ++revision, transitionDuration: crossfade.duration(handoffInstant) };
@@ -403,13 +419,14 @@ export const createRuntime = async (
         verticalBarsMembers.add(element);
       }
       for (const element of accepted.flatMap(candidateSources)) {
+        const newlyProjected = !sources.has(element) || !element.hasAttribute(marker);
         if (!sources.has(element)) {
           sources.set(element, element.getAttribute('aria-hidden'));
           crossfade.play(element, true, handoffInstant || isVerticalBarsSource(element));
-          element.setAttribute(marker, '');
-          element.setAttribute('aria-hidden', 'true');
-          element.dispatchEvent(new CustomEvent('nativeUIShellChange'));
         }
+        element.setAttribute(marker, '');
+        element.setAttribute('aria-hidden', 'true');
+        if (newlyProjected) element.dispatchEvent(new CustomEvent('nativeUIShellChange'));
       }
       const received = pendingActivations;
       pendingActivations = [];
@@ -675,7 +692,7 @@ export const createRuntime = async (
       event.revision < acceptedRevision ||
       event.revision > revision ||
       event.sequence <= lastSequence ||
-      overlayOpen(false)
+      overlayOpen(false, true)
     )
       return;
     // Native may send input before update() resolves on the JS bridge.
@@ -688,7 +705,7 @@ export const createRuntime = async (
     const element = actions.get(event.id);
     if (!element) return;
     const owner = Array.from(sources.keys()).find((source) => source === element || source.contains(element));
-    if (!owner) return;
+    if (!owner || !inVerticalBarsSurface(owner)) return;
     const direct = !blocked(owner) && unprojected(sources.keys(), () => readEnabledCandidate(owner));
     const candidate = direct || read().find((candidate) => candidate.actions.has(event.id));
     const item = candidate?.control.items.find((item) => item.id === event.id);

package/src/native/shared/candidate.ts

@@ -54,6 +54,10 @@ export const appendItem = (
   const labelStyle = getComputedStyle(labelElement);
   const badge = child.querySelector<HTMLElement>('ion-badge');
   const badgeStyle = badge && visible(badge) ? getComputedStyle(badge) : undefined;
+  const outline =
+    isVerticalBarsSource(child) && child.matches('ion-button') && (child as HTMLIonButtonElement).fill === 'outline'
+      ? getComputedStyle(native ?? child)
+      : undefined;
   const item: ShellItem = {
     id: id(child),
     ...frame(child.getBoundingClientRect(), candidate.element.getBoundingClientRect()),
@@ -71,6 +75,12 @@ export const appendItem = (
     fontSize: parseFloat(labelStyle.fontSize),
     fontWeight: parseInt(labelStyle.fontWeight, 10) || 400,
     color: getComputedStyle(native ?? child).color,
+    backgroundColor:
+      isVerticalBarsSource(child) && child.matches('ion-button') && (child as HTMLIonButtonElement).fill === 'solid'
+        ? getComputedStyle(native ?? child).backgroundColor
+        : undefined,
+    borderColor: outline?.borderTopColor,
+    borderWidth: outline ? parseFloat(outline.borderTopWidth) : undefined,
     badge: badgeStyle
       ? { value: badge!.textContent?.trim() ?? '', color: badgeStyle.backgroundColor, textColor: badgeStyle.color }
       : undefined,

package/src/native/shared/dom.ts

@@ -1,4 +1,5 @@
 import { fadeMarker } from './crossfade';
+import { modalUsesVerticalBars } from './modal';
 
 import type { Frame } from '../definitions';
 
@@ -98,7 +99,8 @@ const verticalBarsTags = new Set(['ion-button', 'ion-back-button', 'ion-buttons'
 export const isVerticalBarsSource = (element: HTMLElement): boolean =>
   verticalBarsTags.has(element.localName) &&
   (element.matches('ion-tab-bar') || verticalBarsOwned(element)) &&
-  !element.closest('ion-menu, ion-modal, ion-popover') &&
+  !element.closest('ion-menu, ion-popover') &&
+  modalUsesVerticalBars(element) &&
   !!element.closest('ion-app.ios-theme-vertical-bars');
 
 export const isVerticalBarsBackPosition = (element: HTMLElement): boolean => {
@@ -109,7 +111,8 @@ export const isVerticalBarsBackPosition = (element: HTMLElement): boolean => {
     (back) =>
       back.closest('.ion-page') === page &&
       !back.matches('.ion-cloned-element') &&
-      !back.closest('ion-header[collapse], ion-footer[collapse], ion-menu, ion-modal, ion-popover'),
+      !back.closest('ion-header[collapse], ion-footer[collapse], ion-menu, ion-popover') &&
+      modalUsesVerticalBars(back),
   );
   const rank = (back: HTMLElement) =>
     inFixedToolbar(back) ? 0 : back.closest('ion-header ion-toolbar, ion-footer ion-toolbar') ? 1 : back.closest('ion-toolbar') ? 3 : 2;
@@ -141,11 +144,7 @@ export const isShellDisabled = (element: Element): boolean =>
 
 export const isVerticalBarsToolbarActionShape = (element: HTMLElement): boolean =>
   element.matches('ion-menu-button') ||
-  (element.matches('ion-button') &&
-    !!element.querySelector('ion-icon, svg') &&
-    !childNodesOf(element).some((node) => node.nodeType === 3 && !!node.textContent?.trim()) &&
-    !element.matches('.ion-color, [color]') &&
-    ['default', 'clear'].includes((element as HTMLIonButtonElement).fill ?? element.getAttribute('fill') ?? 'default'));
+  (element.matches('ion-button') && !!element.querySelector('ion-icon[slot="icon-only"], svg[slot="icon-only"]'));
 
 // Placement belongs to the DOM identity for one routed-page epoch. Changes to
 // content/disabled state affect rendering, never its chosen surface.
@@ -161,7 +160,7 @@ export const verticalBarsOwned = (element: HTMLElement): boolean => verticalBars
 export const isVerticalBarsToolbarAction = (element: HTMLElement): boolean =>
   verticalBarsOwned(element) && !isExcluded(element, verticalBarsEnteringPage(element)) && !isShellDisabled(element);
 
-const overlays = 'ion-menu, ion-modal, ion-popover';
+const overlays = 'ion-menu, ion-popover';
 
 /** Shared eligibility for a toolbar action candidate, before placement is decided (prehide) or consumed (projection). */
 export const verticalBarsActionCandidate = (element: HTMLElement): boolean =>
@@ -169,7 +168,8 @@ export const verticalBarsActionCandidate = (element: HTMLElement): boolean =>
   !element.closest('ion-buttons.ios-theme-horizontal-only, ion-button.ios-theme-horizontal-only') &&
   !isPermanentlyExcluded(element) &&
   !isShellDisabled(element) &&
-  !element.closest(overlays);
+  !element.closest(overlays) &&
+  modalUsesVerticalBars(element);
 
 /** Shared eligibility for a back-button candidate; the back button may sit outside a fixed toolbar. */
 export const verticalBarsBackCandidate = (element: HTMLElement): boolean =>
@@ -177,7 +177,8 @@ export const verticalBarsBackCandidate = (element: HTMLElement): boolean =>
   !element.closest('ion-buttons.ios-theme-horizontal-only') &&
   !isPermanentlyExcluded(element) &&
   !isShellDisabled(element) &&
-  !element.closest(overlays);
+  !element.closest(overlays) &&
+  modalUsesVerticalBars(element);
 
 export const verticalBarsToolbarActions = (element: HTMLElement): HTMLElement[] =>
   // Back buttons use the dedicated rail slot; they are never toolbar actions.

package/src/native/shared/modal.ts

@@ -0,0 +1,157 @@
+import type { Frame } from '../definitions';
+
+/** Modal hosts cover the viewport even when their visible dialog is centered. */
+export const modalRailClass = 'ios-theme-vertical-bars-modal';
+const states = new WeakMap<Document, { top?: HTMLIonModalElement }>();
+
+export const topModal = (doc: Document): HTMLIonModalElement | undefined => states.get(doc)?.top;
+export const modalUsesVerticalBars = (element: Element): boolean => {
+  const modal = element.closest('ion-modal');
+  return !modal || modal.classList.contains(modalRailClass);
+};
+
+/** Only the foreground modal may contribute controls; never the covered page. */
+export const inVerticalBarsSurface = (element: Element): boolean => {
+  const modal = topModal(element.ownerDocument);
+  return modal ? element.closest('ion-modal') === modal && modalUsesVerticalBars(element) : !element.closest('ion-modal');
+};
+
+export const observeVerticalBarsModals = (doc: Document): (() => void) => {
+  const win = doc.defaultView!;
+  const state: { top?: HTMLIonModalElement } = {};
+  states.set(doc, state);
+  const presenting = new Set<HTMLIonModalElement>();
+  const dismissed = new WeakSet<HTMLIonModalElement>();
+  const observed = new Set<Element>();
+  const listeners = new AbortController();
+  let stopped = false;
+  let frame = 0;
+  let pointerActive = false;
+  let bounds = '';
+  const toolbarTop = '--ios-theme-vertical-bars-modal-offset-top';
+  const refresh = () => {
+    win.cancelAnimationFrame(frame);
+    frame = 0;
+    if (stopped) return;
+    const app = doc.querySelector('ion-app.ios-theme-vertical-bars');
+    const modals = Array.from(doc.querySelectorAll<HTMLIonModalElement>('ion-modal'));
+    const active = modals.filter(
+      (modal) => !dismissed.has(modal) && ((modal as HTMLIonModalElement & { presented?: boolean }).presented || presenting.has(modal)),
+    );
+    for (const modal of presenting) if (!modal.isConnected) presenting.delete(modal);
+    const top = active.sort((a, b) => a.overlayIndex - b.overlayIndex).slice(-1)[0];
+    let changed = state.top !== top;
+    state.top = top;
+    const nextBounds = top ? JSON.stringify(modalVerticalBarFrame(top)) : '';
+    changed ||= bounds !== nextBounds;
+    bounds = nextBounds;
+    const wanted = new Set<Element>();
+    for (const modal of modals) {
+      const content = modal.shadowRoot?.querySelector<HTMLElement>('[part~="content"]');
+      if (content) wanted.add(content);
+      // offsetWidth is unaffected by Ionic's presentation transforms.
+      const fullWidth = !!content && Math.abs(content.offsetWidth - win.innerWidth) <= 1 && Math.abs(content.offsetLeft) <= 1;
+      const enabled = !!app?.contains(modal) && active.includes(modal) && fullWidth;
+      if (enabled) {
+        const top = modalVerticalBarFrame(modal)?.y ?? 0;
+        const offset = `${top}px`;
+        if (modal.style.getPropertyValue(toolbarTop) !== offset) {
+          modal.style.setProperty(toolbarTop, offset);
+          changed = true;
+        }
+      } else modal.style.removeProperty(toolbarTop);
+      if (modal.classList.contains(modalRailClass) !== enabled) {
+        modal.classList.toggle(modalRailClass, enabled);
+        changed = true;
+      }
+    }
+    if (wanted.size !== observed.size || [...wanted].some((element) => !observed.has(element))) {
+      resize?.disconnect();
+      observer.disconnect();
+      observer.observe(doc.documentElement, observation);
+      observed.clear();
+      for (const element of wanted) {
+        resize?.observe(element);
+        observer.observe(element, { attributes: true, attributeFilter: ['style', 'class'] });
+        observed.add(element);
+      }
+    }
+    if (changed) win.dispatchEvent(new Event('nativeUIShellRefresh'));
+    if (
+      top &&
+      (pointerActive ||
+        Array.from(wanted).some((element) => element.getAnimations().some((animation) => animation.playState === 'running')))
+    )
+      schedule();
+  };
+  const schedule = () => {
+    if (!stopped && !frame) frame = win.requestAnimationFrame(refresh);
+  };
+  const resize = win.ResizeObserver ? new win.ResizeObserver(schedule) : undefined;
+  const observer = new MutationObserver(schedule);
+  const observation = { subtree: true, childList: true, attributes: true, attributeFilter: ['class', 'style'] };
+  observer.observe(doc.documentElement, observation);
+  for (const name of ['ionModalWillPresent', 'ionModalDidPresent', 'ionModalWillDismiss', 'ionModalDidDismiss', 'ionBreakpointDidChange']) {
+    doc.addEventListener(
+      name,
+      (event) => {
+        const modal = event.target as HTMLIonModalElement;
+        if (modal.localName !== 'ion-modal') return;
+        if (name === 'ionModalDidDismiss') {
+          presenting.delete(modal);
+          dismissed.add(modal);
+        } else {
+          presenting.add(modal);
+          dismissed.delete(modal);
+        }
+        refresh();
+      },
+      { capture: true, signal: listeners.signal },
+    );
+  }
+  doc.addEventListener(
+    'pointerdown',
+    (event) => {
+      if ((event.target as Element).closest('ion-modal')) {
+        pointerActive = true;
+        schedule();
+      }
+    },
+    { capture: true, signal: listeners.signal },
+  );
+  for (const name of ['pointerup', 'pointercancel'])
+    doc.addEventListener(
+      name,
+      () => {
+        pointerActive = false;
+        schedule();
+      },
+      { capture: true, signal: listeners.signal },
+    );
+  win.addEventListener('resize', schedule, { signal: listeners.signal });
+  win.addEventListener('nativeUIShellRefresh', schedule, { signal: listeners.signal });
+  refresh();
+  return () => {
+    stopped = true;
+    win.cancelAnimationFrame(frame);
+    observer.disconnect();
+    resize?.disconnect();
+    listeners.abort();
+    if (states.get(doc) !== state) return;
+    states.delete(doc);
+    doc.querySelectorAll<HTMLElement>(`.${modalRailClass}`).forEach((modal) => {
+      modal.classList.remove(modalRailClass);
+      modal.style.removeProperty(toolbarTop);
+    });
+  };
+};
+
+/** Visible modal bounds, clipped at the viewport for Ionic's translated sheets. */
+export const modalVerticalBarFrame = (modal: Element): Frame | undefined => {
+  const rect = modal.shadowRoot?.querySelector('[part~="content"]')?.getBoundingClientRect();
+  const win = modal.ownerDocument.defaultView!;
+  if (!rect) return;
+  const y = Math.max(0, rect.top);
+  const height = Math.min(win.innerHeight, rect.bottom) - y;
+  return height > 0 ? { x: 0, y, width: win.innerWidth, height } : undefined;
+};

package/src/native/vertical-bars-web.ts

@@ -1,3 +1,4 @@
+import { inVerticalBarsSurface, topModal } from './shared/modal';
 import type { NativeUIShellHandle, NativeUIShellOptions, NativeUIShellStatus } from './definitions';
 import { VERTICAL_BARS_TRANSITION_CANCELED } from '../native-integration';
 import {
@@ -74,11 +75,13 @@ export const createVerticalBarsWebProjection = (
     });
   const inEligibleToolbar = (element: HTMLElement) =>
     !!verticalBarsRoot()?.contains(element) &&
+    inVerticalBarsSurface(element) &&
     verticalBarsActionCandidate(element) &&
     !isExcluded(element, verticalBarsEnteringPage(element)) &&
     !verticalBarsPages.isDeparted(element);
   const isEligibleBack = (element: HTMLIonBackButtonElement) =>
     !!verticalBarsRoot()?.contains(element) &&
+    inVerticalBarsSurface(element) &&
     verticalBarsOwned(element) &&
     verticalBarsBackCandidate(element) &&
     !isExcluded(element, verticalBarsEnteringPage(element)) &&
@@ -151,7 +154,10 @@ export const createVerticalBarsWebProjection = (
   const syncAction = (target: HTMLElement, original: HTMLElement) => {
     copyAttributes(target, original);
     target.classList.add('ios-theme-vertical-bars-toolbar-action', 'ion-cloned-element');
-    const label = original.getAttribute('aria-label') ?? original.textContent?.trim();
+    const label =
+      original.getAttribute('aria-label') ??
+      original.shadowRoot?.querySelector('[part~=native]')?.getAttribute('aria-label') ??
+      original.textContent?.trim();
     if (label) target.setAttribute('aria-label', label);
     if ('disabled' in original) (target as HTMLIonButtonElement).disabled = (original as HTMLIonButtonElement).disabled;
     if (original.matches('ion-button')) {
@@ -185,7 +191,7 @@ export const createVerticalBarsWebProjection = (
     }
   };
   const project = (nextBack: HTMLIonBackButtonElement | undefined, groups: ToolbarSource[]) => {
-    root = verticalBarsRoot()!;
+    root = topModal(doc) ?? verticalBarsRoot()!;
     let topOffset = 0;
     if (nextBack) {
       backSource = nextBack;
@@ -269,7 +275,7 @@ export const createVerticalBarsWebProjection = (
     const nextBack = findBack();
     const groups = findToolbarGroups();
     if (!nextBack && !groups.length) return restore();
-    if (sameSources(nextBack, groups)) return syncExisting();
+    if (root === (topModal(doc) ?? currentRoot) && sameSources(nextBack, groups)) return syncExisting();
     restore();
     project(nextBack, groups);
     updates++;
@@ -287,6 +293,8 @@ export const createVerticalBarsWebProjection = (
   };
   const schedule = (): Promise<void> => {
     if (stopped) return Promise.resolve();
+    // Release Web ownership before the native runtime can acknowledge its next frame.
+    if (!enabled()) restore();
     const done = new Promise<void>((resolve) => waiters.push(resolve));
     if (!frame) frame = win.requestAnimationFrame(update);
     return done;
@@ -336,6 +344,7 @@ export const createVerticalBarsWebProjection = (
   doc.addEventListener(VERTICAL_BARS_TRANSITION_CANCELED, pageLifecycle, { capture: true, signal: listeners.signal });
   for (const name of ['ionModalWillPresent', 'ionModalDidDismiss'])
     doc.addEventListener(name, schedule, { capture: true, signal: listeners.signal });
+  win.addEventListener('resize', schedule, { signal: listeners.signal });
   win.addEventListener('nativeUIShellRefresh', schedule, { signal: listeners.signal });
   schedule();