@webview-native-ui/engine 1.0.0 → 1.0.2-0

package/src/controls/shared/modal.ts

@@ -0,0 +1,286 @@
+import { enableSupportIonicOverlays, ionicModalStack } from '../../ionic.js';
+import type { Frame } from '../definitions.js';
+import { prepareSheetLayout, readModalAnimation, type ModalAnimation } from './modal-animation.js';
+
+/** Modal hosts cover the viewport even when their visible dialog is centered. */
+export const modalRailClass = 'ios-theme-vertical-bars-modal';
+const presentations = new WeakMap<Element, { animation: ModalAnimation; frame: Frame } | null>();
+export const modalPresentation = (modal: Element) => presentations.get(modal);
+export const modalPreparing = (modal: Element) => presentations.has(modal) && presentations.get(modal) === null;
+
+const dismissing = new WeakSet<Element>();
+export const modalDismissing = (modal: Element) => dismissing.has(modal);
+interface ModalState {
+  top?: HTMLIonModalElement;
+  moving?: HTMLIonModalElement;
+  stack: HTMLIonModalElement[];
+}
+const states = new WeakMap<Document, ModalState>();
+export const modalStack = (doc: Document): readonly HTMLIonModalElement[] => states.get(doc)?.stack ?? [];
+export const movingModal = (doc: Document) => states.get(doc)?.moving;
+export const modalMotionEvent = 'nativeUIModalMotion';
+
+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');
+};
+
+/** Release Ionic's dormant sheet gesture effect before the leave animation owns opacity.
+ * WillDismiss is emitted only after canDismiss succeeds. A gesture dismissal already
+ * owns its animation and must not be interrupted. Match only Ionic's standard
+ * opacity-only keyframes; leave running and nonmatching effects alone.
+ */
+export const releaseSheetBackdropGesture = (modal: HTMLElement, role?: string): void => {
+  if (role === 'gesture' || !modal.matches('.modal-sheet.ios-theme-vertical-bars-modal')) return;
+  const backdrop = modal.shadowRoot?.querySelector('ion-backdrop');
+  const breakpoint = (modal as HTMLIonModalElement).backdropBreakpoint ?? 0;
+  const expected =
+    breakpoint === 0
+      ? [
+          { offset: 0, opacity: 'var(--backdrop-opacity)' },
+          { offset: 1, opacity: '0.01' },
+        ]
+      : [
+          { offset: 0, opacity: 'var(--backdrop-opacity)' },
+          { offset: 1 - breakpoint, opacity: '0' },
+          { offset: 1, opacity: '0' },
+        ];
+  for (const animation of backdrop?.getAnimations() ?? []) {
+    const effect = animation.effect;
+    if (animation.playState !== 'paused' || !(effect instanceof KeyframeEffect)) continue;
+    const frames = effect.getKeyframes();
+    if (
+      effect.target !== backdrop ||
+      frames.length !== expected.length ||
+      !frames.every(
+        (frame, index) =>
+          frame.offset === expected[index].offset &&
+          frame['opacity'] === expected[index].opacity &&
+          frame.easing === 'linear' &&
+          (frame.composite === 'auto' || frame.composite === 'replace') &&
+          Object.keys(frame).every((key) => ['offset', 'computedOffset', 'easing', 'composite', 'opacity'].includes(key)),
+      )
+    )
+      continue;
+    animation.cancel();
+  }
+};
+
+export const observeVerticalBarsModals = (doc: Document, animate: () => boolean = () => false): (() => void) => {
+  const win = doc.defaultView!;
+  const state: ModalState = { stack: [] };
+  states.set(doc, state);
+  const overlays = enableSupportIonicOverlays(undefined, doc)!;
+  const observed = new Set<Element>();
+  const listeners = new AbortController();
+  let stopped = false;
+  let frame = 0;
+  let pointerActive = false;
+  let touchActive = 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 = ionicModalStack(doc) as HTMLIonModalElement[];
+    state.stack = active;
+    const top = state.stack[state.stack.length - 1];
+    let changed = state.top !== top;
+    state.top = top;
+    if (top && modalPreparing(top)) {
+      const content = top.shadowRoot?.querySelector<HTMLElement>('[part~="content"]');
+      if (content?.getAnimations().some((animation) => animation.playState === 'running')) {
+        const presentation = readModalAnimation(content);
+        if (presentation) {
+          prepareSheetLayout(top);
+          presentations.set(top, presentation);
+        } else presentations.delete(top); // Unsupported custom animations retain the existing projection path.
+        changed = true;
+      }
+    }
+    const nextBounds = top && !modalPreparing(top) ? JSON.stringify(modalVerticalBarFrame(top)) : '';
+    const moved = bounds !== '' && nextBounds !== '' && bounds !== nextBounds;
+    changed ||= bounds !== nextBounds;
+    bounds = nextBounds;
+    const wrapper = top?.shadowRoot?.querySelector<HTMLElement>('[part~="content"]');
+    const animating = wrapper?.getAnimations().some((animation) => animation.playState === 'running') ?? false;
+    const moving =
+      top &&
+      app &&
+      !modalPreparing(top) &&
+      !modalDismissing(top) &&
+      (state.moving === top ? pointerActive || touchActive || animating || moved : moved && (pointerActive || touchActive || animating))
+        ? top
+        : undefined;
+    const appStyle = app && win.getComputedStyle(app);
+    const leftRail = app?.classList.contains('ios-theme-vertical-bars-left') ?? false;
+    const resolvedInset = parseFloat(
+      appStyle?.getPropertyValue(`--ios-theme-vertical-bars-safe-area-${leftRail ? 'left' : 'right'}-resolved`) ?? '',
+    );
+    const inset = Number.isFinite(resolvedInset)
+      ? resolvedInset
+      : parseFloat(appStyle?.getPropertyValue('--ios-theme-vertical-bars-native-inset') ?? '') || 0;
+    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 overlapsRail =
+        !!content &&
+        inset > 0 &&
+        (leftRail ? content.offsetLeft < inset : content.offsetLeft + content.offsetWidth > win.innerWidth - inset);
+      const enabled = !!app?.contains(modal) && active.includes(modal) && (fullWidth || overlapsRail);
+      if (enabled) {
+        const top = modalPreparing(modal) ? 0 : (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 (state.moving !== moving) {
+      const previous = state.moving;
+      state.moving = moving;
+      win.dispatchEvent(new CustomEvent(modalMotionEvent, { detail: { modal: moving ?? previous, moving: !!moving } }));
+      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 CustomEvent('nativeUIRefresh', { detail: { modalMotion: !!state.moving } }));
+    if (
+      top &&
+      (modalPreparing(top) ||
+        (!modalPresentation(top) &&
+          (pointerActive ||
+            touchActive ||
+            !!state.moving ||
+            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);
+  const stopOverlays = overlays.subscribe(({ element, phase, event }) => {
+    if (!element?.matches('ion-modal')) {
+      if (phase === 'change') refresh();
+      return;
+    }
+    const modal = element as HTMLIonModalElement;
+    if (phase === 'willPresent' && animate() && modal.closest('ion-app.ios-theme-vertical-bars')) presentations.set(modal, null);
+    else if (phase === 'didPresent' || phase === 'willDismiss' || phase === 'didDismiss') {
+      if (presentations.delete(modal)) bounds = '';
+    }
+    if (phase === 'willDismiss') {
+      dismissing.add(modal);
+      if (animate()) releaseSheetBackdropGesture(modal, (event as CustomEvent<{ role?: string }> | undefined)?.detail?.role);
+    } else if (phase === 'willPresent' || phase === 'didDismiss') dismissing.delete(modal);
+    refresh();
+  });
+  doc.addEventListener(
+    'pointerdown',
+    (event) => {
+      if ((event.target as Element).closest('ion-modal')) {
+        pointerActive = true;
+        schedule();
+      }
+    },
+    { capture: true, signal: listeners.signal },
+  );
+  // WebKit cancels pointer events when Ionic takes over a touch gesture.
+  // Touch ownership lasts through dragging, including a stationary hold.
+  doc.addEventListener(
+    'touchstart',
+    (event) => {
+      if ((event.target as Element).closest('ion-modal')) {
+        touchActive = true;
+        schedule();
+      }
+    },
+    { capture: true, passive: true, signal: listeners.signal },
+  );
+  for (const name of ['touchend', 'touchcancel'])
+    doc.addEventListener(
+      name,
+      (event) => {
+        touchActive = (event as TouchEvent).touches.length > 0;
+        schedule();
+      },
+      { capture: true, passive: true, signal: listeners.signal },
+    );
+  for (const name of ['pointerup', 'pointercancel'])
+    doc.addEventListener(
+      name,
+      () => {
+        pointerActive = false;
+        schedule();
+      },
+      { capture: true, signal: listeners.signal },
+    );
+  win.addEventListener(
+    'resize',
+    () => {
+      if (state.top) presentations.delete(state.top);
+      schedule();
+    },
+    { signal: listeners.signal },
+  );
+  win.addEventListener('nativeUIRefresh', schedule, { signal: listeners.signal });
+  refresh();
+  return () => {
+    stopped = true;
+    stopOverlays();
+    win.cancelAnimationFrame(frame);
+    observer.disconnect();
+    resize?.disconnect();
+    listeners.abort();
+    if (states.get(doc) !== state) return;
+    states.delete(doc);
+    doc.querySelectorAll('ion-modal').forEach((modal) => presentations.delete(modal));
+    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 presentation = modalPresentation(modal);
+  if (presentation) return presentation.frame;
+  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/controls/shared/projection-id.ts

@@ -0,0 +1,2 @@
+/** Internal identity used to anchor overlays to their native control. */
+export const projectionIds = new WeakMap<Element, string>();

package/src/controls/shared/scroll-placement.ts

@@ -0,0 +1 @@
+export { readScrollPlacement } from '../../index.js';

package/src/controls/shared/tab-bar-width.ts

@@ -0,0 +1,66 @@
+/** Keep the Web fallback at the acknowledged native width, without feeding that
+ * width back as the next layout request (which can progressively shrink a bar). */
+export const createTabBarWidths = (doc: Document) => {
+  const entries = new Map<HTMLElement, { style: HTMLStyleElement; key: string; width: number; cssWidth: number }>();
+  let next = 0;
+  const key = (bar: HTMLElement) => {
+    const computed = doc.defaultView!.getComputedStyle(bar);
+    return JSON.stringify([
+      doc.defaultView!.innerWidth,
+      doc.defaultView!.innerHeight,
+      bar.closest('ion-app')?.className,
+      computed.width,
+      computed.boxSizing,
+      computed.paddingLeft,
+      computed.paddingRight,
+      computed.borderLeftWidth,
+      computed.borderRightWidth,
+      Array.from(bar.children)
+        .filter((child) => !child.classList.contains('ion-cloned-element'))
+        .map((child) => child.textContent),
+    ]);
+  };
+  const remove = (bar: HTMLElement) => {
+    entries.get(bar)?.style.remove();
+    entries.delete(bar);
+    bar.removeAttribute('data-native-tab-width');
+  };
+  return {
+    measure<T>(read: () => T): T {
+      // Compare layout with the source CSS. Gesture classes and transforms must
+      // not discard the measured resting width during a Web handoff.
+      for (const { style } of entries.values()) if (style.sheet) style.sheet.disabled = true;
+      for (const [bar, entry] of entries) if (!bar.isConnected || entry.key !== key(bar)) remove(bar);
+      try {
+        return read();
+      } finally {
+        for (const { style } of entries.values()) if (style.sheet) style.sheet.disabled = false;
+      }
+    },
+    apply(bar: HTMLElement, width: number) {
+      if (!Number.isFinite(width) || width <= 0) return;
+      const previous = entries.get(bar);
+      const computed = doc.defaultView!.getComputedStyle(bar);
+      const inset =
+        computed.boxSizing === 'border-box'
+          ? 0
+          : (['paddingLeft', 'paddingRight', 'borderLeftWidth', 'borderRightWidth'] as const).reduce(
+              (total, property) => total + (parseFloat(computed[property]) || 0),
+              0,
+            );
+      const cssWidth = Math.max(0, width - inset);
+      if (previous && Math.abs(previous.width - width) < 0.1 && Math.abs(previous.cssWidth - cssWidth) < 0.1) return;
+      remove(bar);
+      const sourceKey = key(bar);
+      const token = `tab-${++next}`;
+      const style = doc.createElement('style');
+      bar.setAttribute('data-native-tab-width', token);
+      style.textContent = `[data-native-tab-width="${token}"]{width:${cssWidth}px!important;min-width:${cssWidth}px!important;max-width:${cssWidth}px!important}`;
+      doc.head.append(style);
+      entries.set(bar, { style, key: sourceKey, width, cssWidth });
+    },
+    clear() {
+      for (const bar of entries.keys()) remove(bar);
+    },
+  };
+};

package/src/controls/shared/toolbar-options.ts

@@ -0,0 +1,51 @@
+import { modalUsesVerticalBars } from './modal.js';
+import type { VerticalControlAreaOptions } from '../definitions.js';
+import { controlDefault } from './control-options.js';
+import { childElements, inFixedToolbar, isExcluded, isNativeUIDisabled } from './dom.js';
+
+export const toolbarOptions = (options: VerticalControlAreaOptions, vertical: boolean) => ({
+  buttonGroup: controlDefault(options, 'buttonGroup', vertical),
+  button: controlDefault(options, 'button', vertical),
+  backButton: controlDefault(options, 'backButton', vertical),
+});
+
+export const localToolbarOption = (element: HTMLElement, vertical: boolean): boolean | undefined => {
+  const value = element.getAttribute(vertical ? 'data-vertical-bars' : 'data-horizontal-bars');
+  return value === 'true' ? true : value === 'false' ? false : undefined;
+};
+
+export const horizontalSelected = (element: HTMLElement, options: VerticalControlAreaOptions): boolean => {
+  const group = element.parentElement;
+  if (group?.matches('ion-buttons') && isNativeUIDisabled(group)) return false;
+  return localToolbarOption(element, false) ?? toolbarOptions(options, false)[element.matches('ion-back-button') ? 'backButton' : 'button'];
+};
+
+// Group only if all original children qualify; otherwise selected actions remain individual.
+// Back navigation never joins an ordinary action group.
+export const horizontalToolbarGroup = (element: HTMLElement, options: VerticalControlAreaOptions): boolean => {
+  if (
+    !element.matches('ion-buttons.ios') ||
+    !(localToolbarOption(element, false) ?? toolbarOptions(options, false).buttonGroup) ||
+    !inFixedToolbar(element) ||
+    isExcluded(element) ||
+    isNativeUIDisabled(element)
+  )
+    return false;
+  const children = childElements(element);
+  return (
+    children.length > 0 &&
+    children.every(
+      (child) =>
+        horizontalSelected(child, options) &&
+        !isExcluded(child) &&
+        !isNativeUIDisabled(child) &&
+        (child.matches('ion-menu-button.ios') ||
+          (children.length > 1 &&
+            child.matches('ion-button.ios.button-clear') &&
+            ((child as HTMLIonButtonElement).fill ?? 'clear') === 'clear')),
+    )
+  );
+};
+
+export const inVerticalToolbarLayout = (element: HTMLElement): boolean =>
+  !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');

package/src/controls/shared/transition-identity.ts

@@ -0,0 +1,67 @@
+import type { Candidate } from './candidate.js';
+
+/** Presentation correspondence only. Action IDs always remain source-specific. */
+export const assignToolbarTransitionIds = (candidates: Candidate[]): void => {
+  const entries = candidates.flatMap((candidate) => {
+    const { element, control } = candidate;
+    if (!['button', 'button-group', 'menu-button', 'back-button'].includes(control.kind)) return [];
+    const toolbar = element.closest('ion-toolbar, [role="toolbar"]');
+    if (!toolbar && control.placement !== 'vertical-bars') return [];
+    const page = element.closest('.ion-page, ion-modal') ?? element.ownerDocument.body;
+    const slotOwner = element.closest('ion-buttons') ?? element;
+    const slot = control.toolbarSlot ?? slotOwner.getAttribute('slot') ?? (control.kind === 'back-button' ? 'start' : 'end');
+    return [{ candidate, toolbar, page, slot }];
+  });
+  const counters = new Map<Element, Map<string, number>>();
+  for (const { toolbar, page, slot } of entries) {
+    const counts = counters.get(toolbar ?? page) ?? new Map<string, number>();
+    counters.set(toolbar ?? page, counts);
+    if (slot === 'end') counts.set(slot, (counts.get(slot) ?? 0) + 1);
+  }
+  const identities: { target: { transitionId?: string }; id: string; fallback: string }[] = [];
+  for (const { candidate, toolbar, page, slot } of entries) {
+    const { element, control } = candidate;
+    const section = toolbar?.closest('ion-header, ion-footer');
+    const sectionName = section?.tagName.toLowerCase() ?? 'toolbar';
+    const toolbars = Array.from(page.querySelectorAll('ion-toolbar, [role="toolbar"]')).filter(
+      (node) => (node.closest('ion-header, ion-footer')?.tagName.toLowerCase() ?? 'toolbar') === sectionName,
+    );
+    const scope = [sectionName, toolbar ? toolbars.indexOf(toolbar) : 0];
+    const counts = counters.get(toolbar ?? page)!;
+    // DOM order follows the inline direction. Count from the logical outer edge:
+    // start uses DOM order, end reverses it, including when RTL mirrors the layout.
+    const position = slot === 'end' ? counts.get(slot)! - 1 : (counts.get(slot) ?? 0);
+    counts.set(slot, slot === 'end' ? position : position + 1);
+    const explicitSurface =
+      element.getAttribute('data-transition-id')?.trim() ||
+      (!element.matches('ion-buttons') && control.items.length === 1
+        ? candidate.actions.get(control.items[0].id)?.getAttribute('data-transition-id')?.trim()
+        : undefined);
+    const surfaceId = JSON.stringify(
+      explicitSurface ? ['surface-explicit', ...scope, explicitSurface] : ['group', ...scope, slot, position],
+    );
+    identities.push({
+      target: control,
+      id: surfaceId,
+      fallback: control.id,
+    });
+    for (const [index, item] of control.items.entries()) {
+      const source = candidate.actions.get(item.id);
+      const explicit = source?.getAttribute('data-transition-id')?.trim();
+      // Child positions belong to their surface. Resizing a group cannot renumber the next one.
+      identities.push({
+        target: item,
+        id: explicit
+          ? JSON.stringify(['explicit', ...scope, explicit])
+          : JSON.stringify(['auto', surfaceId, slot === 'end' ? control.items.length - 1 - index : index]),
+        fallback: item.id,
+      });
+    }
+  }
+  const counts = new Map<string, number>();
+  for (const { id } of identities) counts.set(id, (counts.get(id) ?? 0) + 1);
+  // Ambiguous keys must not merge actions or produce duplicate SwiftUI identities.
+  for (const { target, id, fallback } of identities) {
+    target.transitionId = counts.get(id) === 1 ? id : JSON.stringify(['unmatched', fallback]);
+  }
+};

package/src/controls/shared/vertical-bars-geometry.ts

@@ -0,0 +1,92 @@
+import type { Frame, NativeUIVerticalBarFrame } from '../definitions.js';
+
+const measurements = new WeakMap<Element, { frame: Frame; viewport: string }>();
+const viewport = (element: Element) => {
+  const win = element.ownerDocument.defaultView!;
+  const classes = element.closest('ion-app')?.classList;
+  return `${win.innerWidth}:${win.innerHeight}:${classes?.contains('ios-theme-vertical-bars')}:${classes?.contains('ios-theme-vertical-bars-left')}`;
+};
+
+export const validVerticalBarFrame = (frame: Frame) =>
+  [frame.x, frame.y, frame.width, frame.height].every(Number.isFinite) && frame.width > 0 && frame.height > 0;
+
+export const forgetVerticalBarFrame = (element: Element) => measurements.delete(element);
+
+export const rememberVerticalBarFrame = (element: Element, frame: Frame) => {
+  if (validVerticalBarFrame(frame)) measurements.set(element, { frame, viewport: viewport(element) });
+};
+
+export const verticalBarFrame = (element: Element): Frame | undefined => {
+  const saved = measurements.get(element);
+  return saved?.viewport === viewport(element) ? saved.frame : undefined;
+};
+
+/** Convert the native viewport rectangle into the clone's positioning container. */
+export const alignVerticalBarClone = (clone: HTMLElement, source: Element, parent: HTMLElement) => {
+  const frame = verticalBarFrame(source);
+  if (!frame) return;
+  const origin = parent.getBoundingClientRect();
+  const parentStyle = parent.ownerDocument.defaultView!.getComputedStyle(parent);
+  // clientLeft/clientTop round subpixel glass borders to whole CSS pixels.
+  const borderLeft = parseFloat(parentStyle.borderLeftWidth) || 0;
+  const borderTop = parseFloat(parentStyle.borderTopWidth) || 0;
+  // Absolute children use the padding edge, not the outer edge of a glass group.
+  Object.assign(clone.style, {
+    position: 'absolute',
+    left: `${frame.x - origin.left - borderLeft}px`,
+    top: `${frame.y - origin.top - borderTop}px`,
+    right: 'auto',
+    bottom: 'auto',
+    width: `${frame.width}px`,
+    height: `${frame.height}px`,
+    minWidth: `${frame.width}px`,
+    maxWidth: `${frame.width}px`,
+    minHeight: `${frame.height}px`,
+    maxHeight: `${frame.height}px`,
+    margin: '0',
+    boxSizing: 'border-box',
+  });
+};
+
+export const alignVerticalTabBar = (
+  tabBar: HTMLElement,
+  frame: NativeUIVerticalBarFrame,
+  items: Map<HTMLElement, NativeUIVerticalBarFrame>,
+): (() => void) => {
+  const doc = tabBar.ownerDocument;
+  const style = doc.createElement('style');
+  const token = `rail-${Math.random().toString(36).slice(2)}`;
+  const selector = `[data-native-rail-geometry="${token}"]`;
+  const origin = (tabBar.offsetParent as HTMLElement | null)?.getBoundingClientRect() ?? { left: 0, top: 0 };
+  tabBar.setAttribute('data-native-rail-geometry', token);
+  // Preserve the measured shape. Only older binaries need the capsule fallback.
+  const radius = (rect: NativeUIVerticalBarFrame) =>
+    Number.isFinite(rect.cornerRadius) && rect.cornerRadius! >= 0 ? rect.cornerRadius! : Math.min(rect.width, rect.height) / 2;
+  const box = (rect: NativeUIVerticalBarFrame, x: number, y: number) =>
+    `position:absolute!important;left:${rect.x - x}px!important;top:${rect.y - y}px!important;right:auto!important;bottom:auto!important;width:${rect.width}px!important;min-width:${rect.width}px!important;max-width:${rect.width}px!important;height:${rect.height}px!important;min-height:${rect.height}px!important;max-height:${rect.height}px!important;margin:0!important;padding:0!important;box-sizing:border-box!important;border-radius:${radius(rect)}px!important;`;
+  style.textContent =
+    `${selector}{${box(frame, origin.left, origin.top)}}` +
+    [...items]
+      .map(([element, rect]) => {
+        const index = Array.from(tabBar.children).indexOf(element) + 1;
+        return `${selector}>:nth-child(${index}){${box(rect, frame.x, frame.y)}}${selector}>:nth-child(${index})::part(native){min-height:0!important}`;
+      })
+      .join('');
+  doc.head.append(style);
+  const win = doc.defaultView!;
+  const measuredViewport = viewport(tabBar);
+  const stop = () => {
+    observer.disconnect();
+    win.removeEventListener('resize', stop);
+    style.remove();
+    if (tabBar.getAttribute('data-native-rail-geometry') === token) tabBar.removeAttribute('data-native-rail-geometry');
+  };
+  const observer = new MutationObserver((records) => {
+    if (viewport(tabBar) !== measuredViewport || records.some((record) => record.type === 'childList')) stop();
+  });
+  observer.observe(tabBar, { childList: true });
+  const app = tabBar.closest('ion-app');
+  if (app) observer.observe(app, { attributes: true, attributeFilter: ['class'] });
+  win.addEventListener('resize', stop);
+  return stop;
+};

package/src/controls/shared/vertical-navigation.ts

@@ -0,0 +1,34 @@
+/** Mirror each Web page's ancestry without depending on tab selection timing. */
+export const createVerticalNavigation = () => {
+  const paths = new WeakMap<HTMLElement, HTMLElement[]>();
+  let transition: { entering: HTMLElement; leaving?: HTMLElement; before: HTMLElement[]; after: HTMLElement[] } | undefined;
+  return {
+    begin(entering: HTMLElement, leaving?: HTMLElement, direction?: 'forward' | 'back' | 'root') {
+      const before = leaving ? (paths.get(leaving) ?? [leaving]) : [];
+      const index = before.indexOf(entering);
+      const after =
+        direction === 'root'
+          ? [entering]
+          : index >= 0
+            ? before.slice(0, index + 1)
+            : direction === 'back'
+              ? [entering]
+              : [...before, entering];
+      const current = { entering, leaving, before, after };
+      transition = current;
+      return (canceled: boolean) => {
+        if (transition !== current) return false;
+        if (canceled) {
+          if (leaving) paths.set(leaving, before);
+        } else paths.set(entering, after);
+        transition = undefined;
+        return true;
+      };
+    },
+    read(page: HTMLElement): HTMLElement[] {
+      if (transition?.entering === page) return transition.after;
+      if (transition?.leaving === page) return transition.before;
+      return paths.get(page) ?? [page];
+    },
+  };
+};