@rdlabo/capacitor-native-ui 0.0.0-stage → 1.2.1

package/src/native/shared/bridge.ts

@@ -0,0 +1,18 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+
+// A failed bridge must not leave the source inaccessible indefinitely.
+export const bounded = <T>(promise: Promise<T>): Promise<T> =>
+  new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Native UI bridge timed out')), 5000);
+    promise.then(resolve, reject).finally(() => clearTimeout(timer));
+  });
+
+/** A timed-out registration still owns a native resource if it eventually succeeds. */
+export const boundedListener = async (registration: Promise<PluginListenerHandle>): Promise<PluginListenerHandle> => {
+  try {
+    return await bounded(registration);
+  } catch (error) {
+    void registration.then((listener) => listener.remove()).catch(() => {});
+    throw error;
+  }
+};

package/src/native/shared/candidate.ts

@@ -0,0 +1,162 @@
+import type { NativeUIControl, NativeUIItem, NativeUIControlKind, NativeUIComponent, VerticalControlAreaOptions } from '../definitions';
+import { frame, isDark, isVerticalBarsSource, text, visible } from './dom';
+import { iconSource, type createIconRenderer } from './icons';
+
+export interface Candidate {
+  assets?: { signature: string; render(renderer: ReturnType<typeof createIconRenderer>): Promise<void> };
+  buttonProjection?: VerticalControlAreaOptions['buttonProjection'];
+  buttonDefaultFill?: VerticalControlAreaOptions['buttonDefaultFill'];
+  element: HTMLElement;
+  sources?: HTMLElement[];
+  control: NativeUIControl;
+  actions: Map<string, HTMLElement>;
+  icons: { item: NativeUIItem; source: string; field?: 'closeIcon' }[];
+}
+
+export type Identify = (element: HTMLElement) => string;
+type ItemElement = HTMLElement & { disabled?: boolean; selected?: boolean };
+
+export const createCandidate = (
+  element: HTMLElement,
+  kind: NativeUIComponent | NativeUIControlKind,
+  id: Identify,
+  options: VerticalControlAreaOptions = {},
+): Candidate => {
+  const rect = element.getBoundingClientRect();
+  const style = getComputedStyle(element);
+  return {
+    element,
+    buttonProjection: options.buttonProjection,
+    buttonDefaultFill: options.buttonDefaultFill,
+    control: {
+      id: id(element),
+      kind:
+        (
+          {
+            'ion-button': 'button',
+            'ion-buttons': 'button-group',
+            'ion-back-button': 'back-button',
+            'ion-menu-button': 'menu-button',
+            'ion-tab-bar': 'tab-bar',
+            'ion-segment': 'segment',
+            'ion-fab': 'floating-action-button',
+          } as Partial<Record<string, NativeUIControlKind>>
+        )[kind] ?? (kind as NativeUIControlKind),
+      ...frame(rect),
+      items: [],
+      dark: isDark(style),
+      rtl: style.direction === 'rtl',
+    },
+    actions: new Map(),
+    icons: [],
+  };
+};
+
+// Shared text, artwork, geometry and action data; component rules stay with their readers.
+export const appendItem = (
+  candidate: Candidate,
+  child: HTMLElement,
+  id: Identify,
+  content: ParentNode = child,
+  label = text(child),
+): NativeUIItem | undefined => {
+  if (
+    !visible(child, isVerticalBarsSource(candidate.element)) ||
+    child.querySelector('input, button, a, img, canvas, video, ion-spinner, ion-avatar')
+  )
+    return;
+  const icons = Array.from(content.querySelectorAll<HTMLElement>('ion-icon'));
+  const directSVGs = Array.from(content.querySelectorAll<SVGElement>('svg'));
+  if (icons.length + directSVGs.length > 1) return undefined;
+  const svg = directSVGs[0] ?? icons[0]?.shadowRoot?.querySelector<SVGElement>('svg');
+  if (icons.length && !svg) return undefined; // ion-icon has not finished loading.
+  const labelElement = content.querySelector('[part="text"], ion-label') ?? child;
+  const native = child.shadowRoot?.querySelector('[part="native"]');
+  const labelStyle = getComputedStyle(labelElement);
+  const badge = child.querySelector<HTMLElement>('ion-badge');
+  const badgeStyle = badge && visible(badge) ? getComputedStyle(badge) : undefined;
+  const sourceFill = (child as HTMLIonButtonElement).fill;
+  const projectionOwner = [child, child.closest('ion-buttons')].find((element) =>
+    element?.matches('[data-projection="source"], [data-projection="system"], .ios-theme-projection-source, .ios-theme-projection-system'),
+  );
+  const attributeProjection = projectionOwner?.getAttribute('data-projection');
+  const projection =
+    attributeProjection === 'source' || attributeProjection === 'system'
+      ? attributeProjection
+      : projectionOwner
+        ? projectionOwner.classList.contains('ios-theme-projection-system')
+          ? 'system'
+          : 'source'
+        : candidate.buttonProjection;
+  const systemButton = projection !== 'source' && isVerticalBarsSource(child) && child.matches('ion-button, ion-menu-button');
+  // Ionic defaults buttons inside ion-buttons to clear, even when the app defaults to solid.
+  const defaultFill = child.closest('ion-buttons') ? 'clear' : candidate.buttonDefaultFill;
+  const fill = !sourceFill || sourceFill === 'default' ? defaultFill : sourceFill;
+  const buttonFill =
+    !systemButton &&
+    isVerticalBarsSource(child) &&
+    child.matches('ion-button') &&
+    (fill === 'clear' || fill === 'solid' || fill === 'outline')
+      ? fill
+      : undefined;
+  const outline = buttonFill === 'outline' ? getComputedStyle(native ?? child) : undefined;
+  const item: NativeUIItem = {
+    id: id(child),
+    ...frame(child.getBoundingClientRect(), candidate.element.getBoundingClientRect()),
+    label,
+    accessibilityLabel:
+      child.getAttribute('aria-label') ??
+      native?.getAttribute('aria-label') ??
+      (icons[0]?.getAttribute('aria-hidden') === 'true' ? null : icons[0]?.getAttribute('aria-label')) ??
+      label,
+    disabled:
+      !!(child as ItemElement).disabled ||
+      !!(candidate.element as ItemElement).disabled ||
+      getComputedStyle(child).pointerEvents === 'none',
+    selected: !!(child as ItemElement).selected,
+    fontSize: parseFloat(labelStyle.fontSize),
+    fontWeight: parseInt(labelStyle.fontWeight, 10) || 400,
+    color: systemButton ? 'currentColor' : getComputedStyle(native ?? child).color,
+    iconTemplate: systemButton ? true : undefined,
+    buttonFill,
+    backgroundColor: buttonFill === '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,
+  };
+  if (svg) {
+    const source = iconSource(svg);
+    if (!source) return undefined;
+    const size = (icons[0] ?? svg).getBoundingClientRect();
+    item.iconWidth = size.width;
+    item.iconHeight = size.height;
+    if (!size.width || !size.height) return undefined;
+    item.iconPosition = (icons[0] ?? svg).getAttribute('slot') === 'end' ? 'trailing' : 'leading';
+    candidate.icons.push({ item, source });
+  }
+  if (native && child.matches('ion-button, ion-back-button')) {
+    const style = getComputedStyle(native);
+    const icon = icons[0] ?? svg;
+    const iconStyle = icon && getComputedStyle(icon);
+    const leadingMargin = parseFloat(iconStyle?.marginInlineStart ?? '') || 0;
+    const trailingMargin = parseFloat(iconStyle?.marginInlineEnd ?? '') || 0;
+    const trailing = item.iconPosition === 'trailing';
+    const inner = native.querySelector('.button-inner');
+    const gap = inner ? parseFloat(getComputedStyle(inner).columnGap) || 0 : 0;
+    // UIKit centers the title/image pair using its insets. Include Ionic's
+    // border and negative outer icon margin instead of applying a fixed offset.
+    item.contentInsetLeading =
+      (parseFloat(style.paddingInlineStart) || 0) +
+      (parseFloat(style.borderInlineStartWidth) || 0) +
+      (!trailing || !label ? leadingMargin : 0);
+    item.contentInsetTrailing =
+      (parseFloat(style.paddingInlineEnd) || 0) + (parseFloat(style.borderInlineEndWidth) || 0) + (trailing || !label ? trailingMargin : 0);
+    item.imagePadding = label && icon ? gap + (trailing ? leadingMargin : trailingMargin) : 0;
+  }
+  if (!label && !svg) return undefined;
+  candidate.control.items.push(item);
+  candidate.actions.set(item.id, child);
+  return item;
+};

package/src/native/shared/clipping.ts

@@ -0,0 +1,24 @@
+export function* projectionAncestors(element: HTMLElement): Generator<HTMLElement> {
+  let current: HTMLElement | null = element;
+  while (current) {
+    const root = current.getRootNode();
+    current = current.assignedSlot ?? current.parentElement ?? (root instanceof ShadowRoot ? (root.host as HTMLElement) : null);
+    if (current) yield current;
+  }
+}
+
+export const fitsClip = (element: HTMLElement): boolean => {
+  const rect = element.getBoundingClientRect();
+  for (const ancestor of projectionAncestors(element)) {
+    const style = getComputedStyle(ancestor);
+    if (style.transform !== 'none' && !new DOMMatrixReadOnly(style.transform).isIdentity) return false;
+    const bounds = ancestor.getBoundingClientRect();
+    const left = bounds.left + ancestor.clientLeft;
+    const top = bounds.top + ancestor.clientTop;
+    if (/^(hidden|clip|scroll|auto)$/.test(style.overflowX) && (rect.left < left - 1 || rect.right > left + ancestor.clientWidth + 1))
+      return false;
+    if (/^(hidden|clip|scroll|auto)$/.test(style.overflowY) && (rect.top < top - 1 || rect.bottom > top + ancestor.clientHeight + 1))
+      return false;
+  }
+  return true;
+};

package/src/native/shared/crossfade.ts

@@ -0,0 +1,67 @@
+export const handoffDuration = 180;
+export const fadeMarker = 'data-native-ui-fading';
+
+/** Only visual opacity animates; the runtime transfers input/accessibility ownership once. */
+export const createCrossfade = (win: Window) => {
+  const active = new Map<HTMLElement, Animation>();
+  const retired = new Set<HTMLElement>();
+  const reduced = win.matchMedia('(prefers-reduced-motion: reduce)');
+  const finish = (element: HTMLElement, animation: Animation) => {
+    if (active.get(element) !== animation) return;
+    active.delete(element);
+    element.removeAttribute(fadeMarker);
+    animation.cancel();
+    if (retired.delete(element)) element.remove();
+  };
+  const cancelAll = () => {
+    for (const [element, animation] of active) finish(element, animation);
+  };
+  reduced.addEventListener('change', cancelAll);
+  const api = {
+    duration: (instant = false) => (reduced.matches || instant ? 0 : handoffDuration),
+    play(element: HTMLElement, toNative: boolean, instant = false) {
+      const previous = active.get(element);
+      const current = Number(win.getComputedStyle(element).opacity);
+      previous?.cancel();
+      active.delete(element);
+      const opacity = Number(win.getComputedStyle(element).opacity);
+      // Tab switches skip the opacity handoff so a retiring native snapshot cannot linger.
+      if (reduced.matches || instant || !element.isConnected) {
+        element.removeAttribute(fadeMarker);
+        return;
+      }
+      element.setAttribute(fadeMarker, '');
+      const animation = element.animate([{ opacity: previous ? current : toNative ? opacity : 0 }, { opacity: toNative ? 0 : opacity }], {
+        duration: handoffDuration,
+        easing: 'ease-in-out',
+        fill: 'both',
+      });
+      active.set(element, animation);
+      void animation.finished.then(
+        () => finish(element, animation),
+        () => finish(element, animation),
+      );
+    },
+    retire(element: HTMLElement, instant = false) {
+      element.inert = true;
+      element.setAttribute('aria-hidden', 'true');
+      element.style.setProperty('pointer-events', 'none', 'important');
+      if (!api.duration(instant) || !element.isConnected) {
+        const previous = active.get(element);
+        if (previous) finish(element, previous);
+        element.remove();
+        return;
+      }
+      retired.add(element);
+      api.play(element, true);
+    },
+    async settled() {
+      await Promise.all(Array.from(active.values(), (animation) => animation.finished.catch(() => {})));
+    },
+    destroy() {
+      reduced.removeEventListener('change', cancelAll);
+      cancelAll();
+    },
+  };
+  return api;
+};

package/src/native/shared/diagnostics.ts

@@ -0,0 +1,13 @@
+/** Opt-in diagnostics. Never log props, action data, or application exception messages. */
+export const createDiagnostics = (enabled = false) => {
+  const elements = new WeakMap<HTMLElement, Set<string>>();
+  const global = new Set<string>();
+  return (reason: string, element?: HTMLElement): void => {
+    if (!enabled) return;
+    const seen = element ? (elements.get(element) ?? new Set<string>()) : global;
+    if (seen.has(reason)) return;
+    seen.add(reason);
+    if (element) elements.set(element, seen);
+    console.info(`[Native UI] ${reason}`, ...(element ? [element] : []));
+  };
+};

package/src/native/shared/dom.ts

@@ -0,0 +1,304 @@
+import { fadeMarker } from './crossfade';
+import { modalUsesVerticalBars } from './modal';
+
+import type { Frame } from '../definitions';
+
+export const marker = 'data-native-ui-projected';
+// Scoped runtimes (Stencil slot emulation) patch child accessors on upgraded
+// elements and may report none before hydration; the prototype getter still
+// reports the real light DOM.
+const childNodesGet = typeof Node === 'undefined' ? undefined : Object.getOwnPropertyDescriptor(Node.prototype, 'childNodes')?.get;
+export const childNodesOf = (element: Element): Node[] =>
+  childNodesGet ? Array.from(childNodesGet.call(element)) : Array.from(element.childNodes);
+export const childElements = (element: Element): HTMLElement[] =>
+  childNodesOf(element).filter((node) => node.nodeType === 1) as HTMLElement[];
+export const prehiddenClass = 'native-ui-prehidden';
+export const prehideRootClass = 'native-ui-prehide';
+export const rejectedClass = 'native-ui-rejected';
+export const verticalBarsBackWebClass = 'ios-theme-vertical-bars-back-web-owned';
+const prehideClasses = new Set([prehiddenClass, prehideRootClass]);
+export const prehideOnlyMutation = (record: MutationRecord): boolean => {
+  if (record.attributeName !== 'class' || record.oldValue === null) return false;
+  const withoutPrehide = (value: string) =>
+    value
+      .split(/\s+/)
+      .filter((name) => name && !prehideClasses.has(name))
+      .join(' ');
+  return withoutPrehide(record.oldValue) === withoutPrehide((record.target as Element).getAttribute('class') ?? '');
+};
+
+export const withoutPrehide = <T>(element: HTMLElement, read: () => T): T => {
+  const changed: HTMLElement[] = [];
+  for (let current: HTMLElement | null = element; current; current = current.parentElement) {
+    if (current.classList.contains(prehiddenClass)) {
+      current.classList.remove(prehiddenClass);
+      changed.push(current);
+    }
+  }
+  const root = element.ownerDocument.documentElement;
+  if (element.matches('ion-back-button') && root.classList.contains(prehideRootClass)) {
+    root.classList.remove(prehideRootClass);
+    changed.push(root);
+  }
+  try {
+    return read();
+  } finally {
+    changed.forEach((current) => current.classList.add(current === root ? prehideRootClass : prehiddenClass));
+  }
+};
+export const isDark = (style: CSSStyleDeclaration): boolean => {
+  const themeScheme = style.getPropertyValue('--ios27-color-scheme').trim();
+  if (themeScheme) return themeScheme === 'dark';
+  const background = style.getPropertyValue('--ion-background-color-rgb').match(/\d+/g)?.slice(0, 3).map(Number);
+  if (background?.length === 3) return background[0] * 0.2126 + background[1] * 0.7152 + background[2] * 0.0722 < 128;
+  const schemes = (style.colorScheme ?? '').split(/\s+/);
+  if (schemes.includes('dark') && !schemes.includes('light')) return true;
+  if (schemes.includes('light') && !schemes.includes('dark')) return false;
+  return typeof window !== 'undefined' && !!window.matchMedia?.('(prefers-color-scheme: dark)').matches;
+};
+const permanentlyExcluded = '.ios-theme-disabled, .ios26-disabled, .ion-cloned-element, [hidden], [inert]';
+export const excluded = `${permanentlyExcluded}, .ion-page-hidden, .ion-page-invisible`;
+const enteringPages = new WeakSet<HTMLElement>();
+export const setVerticalBarsEnteringPage = (page: HTMLElement, entering: boolean): void => {
+  if (entering) enteringPages.add(page);
+  else enteringPages.delete(page);
+};
+export const verticalBarsEnteringPage = (element: HTMLElement): HTMLElement | undefined => {
+  const page = element.closest<HTMLElement>('.ion-page-invisible');
+  return page && enteringPages.has(page) && page.closest('ion-app.ios-theme-vertical-bars') ? page : undefined;
+};
+export const createVerticalBarsPageState = () => {
+  const departed = new WeakSet<HTMLElement>();
+  return {
+    isDeparted(element: HTMLElement): boolean {
+      const page = element.closest<HTMLElement>('.ion-page');
+      return !!page && departed.has(page) && !!element.closest('ion-app.ios-theme-vertical-bars');
+    },
+    lifecycle(event: Event): void {
+      // Avoid instanceof so stale listeners stay safe after global teardown.
+      const page = event.target && (event.target as Node).nodeType === 1 ? (event.target as HTMLElement) : undefined;
+      if (!page?.matches('.ion-page')) return;
+      const entering = event.type === 'ionViewWillEnter';
+      if (entering || event.type === 'ionViewDidEnter') departed.delete(page);
+      else if (event.type === 'ionViewWillLeave' || event.type === 'ionViewDidLeave') departed.add(page);
+      setVerticalBarsEnteringPage(page, entering);
+    },
+    cancel(entering?: HTMLElement, leaving?: HTMLElement): void {
+      if (entering) {
+        departed.add(entering);
+        setVerticalBarsEnteringPage(entering, false);
+      }
+      if (leaving) departed.delete(leaving);
+    },
+  };
+};
+const disabledButtonGroup = 'ion-buttons:is(.ios-theme-disabled, .ios26-disabled)';
+const nativeUIDisabledSelector = '.native-ui-disabled, [data-native-ui="disabled"]';
+
+export const isDisabledButtonGroupChild = (element: HTMLElement): boolean =>
+  element.matches('ion-button') && element.parentElement?.matches(disabledButtonGroup) === true;
+
+const verticalBarsTags = new Set(['ion-button', 'ion-back-button', 'ion-buttons', 'ion-menu-button', 'ion-tab-bar']);
+
+export const isVerticalBarsSource = (element: HTMLElement): boolean =>
+  !element.closest('[data-native-ui-placement="element"]') &&
+  (element.matches(
+    '[data-native-ui-placement="rail"][data-native-ui="button"], [data-native-ui-placement="rail"][data-native-ui="back-button"]',
+  ) ||
+    (verticalBarsTags.has(element.localName) &&
+      (element.matches('ion-tab-bar') || verticalBarsOwned(element)) &&
+      !element.closest('ion-menu, ion-popover') &&
+      modalUsesVerticalBars(element) &&
+      !!element.closest('ion-app.ios-theme-vertical-bars')));
+
+export const isVerticalBarsBackPosition = (element: HTMLElement): boolean => {
+  if (element.closest('ion-header[collapse], ion-footer[collapse]')) return false;
+  const page = element.closest('.ion-page');
+  if (!page) return true;
+  const candidates = Array.from(page.querySelectorAll<HTMLElement>('ion-back-button')).filter(
+    (back) =>
+      back.closest('.ion-page') === page &&
+      !back.matches('.ion-cloned-element') &&
+      !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;
+  const best = candidates.reduce<HTMLElement | undefined>(
+    (winner, back) => (!winner || rank(back) < rank(winner) ? back : winner),
+    undefined,
+  );
+  return best === element;
+};
+
+export const preferredVerticalBarsBack = <T extends HTMLElement>(elements: T[], doc: Document): T | undefined => {
+  const pages = Array.from(doc.querySelectorAll('.ion-page'));
+  const pageOrder = (element: Element) => pages.indexOf(element.closest('.ion-page')!);
+  return elements.sort((a, b) => pageOrder(b) - pageOrder(a) || Number(!!b.closest('ion-header')) - Number(!!a.closest('ion-header')))[0];
+};
+
+const excludedBy = (element: HTMLElement, selector: string): boolean => {
+  const owner = element.closest<HTMLElement>(selector);
+  return !!owner && !(element.parentElement === owner && isDisabledButtonGroupChild(element));
+};
+
+export const isPermanentlyExcluded = (element: HTMLElement): boolean => excludedBy(element, permanentlyExcluded);
+export const isExcluded = (element: HTMLElement, enteringPage?: HTMLElement): boolean =>
+  excludedBy(element, `${permanentlyExcluded}, .ion-page-hidden`) || (!!element.closest('.ion-page-invisible') && !enteringPage);
+
+// A shared native surface must not cover an opted-out descendant either.
+export const isNativeUIDisabled = (element: Element): boolean =>
+  !!element.closest(nativeUIDisabledSelector) || !!element.querySelector(nativeUIDisabledSelector);
+
+export const isVerticalBarsToolbarActionShape = (element: HTMLElement): boolean =>
+  element.matches('ion-menu-button') ||
+  (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.
+const verticalBarsPlacement = new WeakMap<HTMLElement, boolean>();
+export const setVerticalBarsPlacement = (element: HTMLElement, rail: boolean): void => {
+  verticalBarsPlacement.set(element, rail);
+};
+export const clearVerticalBarsPlacement = (element: HTMLElement): void => {
+  verticalBarsPlacement.delete(element);
+};
+// Explicit Web placement remains authoritative even when added after initial capture.
+export const verticalBarsOwned = (element: HTMLElement): boolean =>
+  verticalBarsPlacement.get(element) === true &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only, ion-button.ios-theme-horizontal-only');
+
+export const isVerticalBarsToolbarAction = (element: HTMLElement): boolean =>
+  verticalBarsOwned(element) && !isExcluded(element, verticalBarsEnteringPage(element)) && !isNativeUIDisabled(element);
+
+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 =>
+  !element.matches('[data-native-ui="button"], [data-native-ui="back-button"]') &&
+  !element.querySelector('[data-native-ui="button"], [data-native-ui="back-button"]') &&
+  inFixedToolbar(element) &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only, ion-button.ios-theme-horizontal-only') &&
+  !isPermanentlyExcluded(element) &&
+  !isNativeUIDisabled(element) &&
+  !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 =>
+  !element.hasAttribute('data-native-ui') &&
+  isVerticalBarsBackPosition(element) &&
+  !element.closest('ion-buttons.ios-theme-horizontal-only') &&
+  !isPermanentlyExcluded(element) &&
+  !isNativeUIDisabled(element) &&
+  !element.closest(overlays) &&
+  modalUsesVerticalBars(element);
+
+export const verticalBarsToolbarActions = (element: HTMLElement): HTMLElement[] =>
+  // Back buttons use the dedicated rail slot; they are never toolbar actions.
+  childElements(element).filter((child) => !child.matches('ion-back-button') && isVerticalBarsToolbarAction(child));
+
+export const isVerticalBarsToolbarGroup = (element: HTMLElement): boolean => {
+  return (
+    element.matches('ion-buttons') &&
+    verticalBarsOwned(element) &&
+    !element.matches('.ios-theme-disabled, .ios26-disabled') &&
+    !isNativeUIDisabled(element)
+  );
+};
+
+export const toolbarTextMarker = 'data-native-ui-toolbar-text';
+
+export const syncToolbarText = (doc: Document): void => {
+  for (const toolbar of Array.from(
+    doc.querySelectorAll<HTMLElement>(`ion-app.ios-theme-vertical-bars ion-toolbar, ion-toolbar[${toolbarTextMarker}]`),
+  )) {
+    toolbar.toggleAttribute(
+      toolbarTextMarker,
+      !!toolbar.closest('ion-app.ios-theme-vertical-bars') &&
+        childNodesOf(toolbar).some((node) => node.nodeType === Node.TEXT_NODE && !!node.textContent?.trim()),
+    );
+  }
+};
+
+export const activateProjectedElement = (element: HTMLElement): void => {
+  const target = element.matches('ion-button, ion-back-button, ion-menu-button')
+    ? element.shadowRoot?.querySelector<HTMLElement>('[part~="native"]')
+    : undefined;
+  (target ?? element).click();
+};
+
+export const unprojected = <T>(elements: Iterable<HTMLElement>, read: () => T): T => {
+  const list = Array.from(elements);
+  const hidden = list.filter((element) => element.hasAttribute(marker));
+  const webHidden = list.filter((element) => element.hasAttribute('data-native-ui-web-source'));
+  hidden.forEach((element) => element.removeAttribute(marker));
+  webHidden.forEach((element) => element.removeAttribute('data-native-ui-web-source'));
+  try {
+    return read();
+  } finally {
+    hidden.forEach((element) => element.setAttribute(marker, ''));
+    webHidden.forEach((element) => element.setAttribute('data-native-ui-web-source', ''));
+  }
+};
+
+const readVisible = (element: HTMLElement, allowOutsideViewport: boolean): boolean => {
+  const enteringPage = isVerticalBarsSource(element) ? verticalBarsEnteringPage(element) : undefined;
+  if (!element.isConnected || isExcluded(element, enteringPage) || isNativeUIDisabled(element)) return false;
+  for (let current: HTMLElement | null = element; current; current = current.parentElement) {
+    const style = getComputedStyle(current);
+    if (
+      style.display === 'none' ||
+      style.visibility !== 'visible' ||
+      (Number(style.opacity) === 0 && !current.hasAttribute(fadeMarker) && current !== enteringPage)
+    )
+      return false;
+    // Ordinary controls on moving/collapsing/custom transformed surfaces stay in Web coordinates.
+    // VerticalBars rail controls are placed independently of their Web coordinates and must remain
+    // owned while Ionic transforms the content behind an open menu.
+    if (
+      !allowOutsideViewport &&
+      style.transform !== 'none' &&
+      !new DOMMatrixReadOnly(style.transform).isIdentity &&
+      current !== element &&
+      !current.matches('ion-tab-bar')
+    )
+      return false;
+  }
+  const rect = element.getBoundingClientRect();
+  return (
+    rect.width > 0 &&
+    rect.height > 0 &&
+    (allowOutsideViewport || (rect.left >= -1 && rect.top >= -1 && rect.right <= innerWidth + 1 && rect.bottom <= innerHeight + 1))
+  );
+};
+
+export const visible = (element: HTMLElement, allowOutsideViewport = false): boolean =>
+  withoutPrehide(element, () => readVisible(element, allowOutsideViewport));
+
+export const frame = (rect: DOMRect, origin?: DOMRect): Frame => ({
+  x: rect.x - (origin?.x ?? 0),
+  y: rect.y - (origin?.y ?? 0),
+  width: rect.width,
+  height: rect.height,
+});
+
+export const text = (element: Element): string => {
+  if (element.matches('ion-icon, svg, ion-badge, .ios27-segment-lens, .ion-cloned-element')) return '';
+  return childNodesOf(element)
+    .map((node) => (node.nodeType === 3 ? node.textContent : node.nodeType === 1 ? text(node as Element) : ''))
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+export const inFixedToolbar = (element: Element): boolean => {
+  const edge = element.closest('ion-toolbar')?.parentElement;
+  const verticalBars = !!element.closest('ion-app.ios-theme-vertical-bars');
+  return (
+    !!edge?.matches('ion-header, ion-footer') &&
+    !element.closest('ion-content') &&
+    !edge.hasAttribute('collapse') &&
+    (verticalBars || !edge.matches('.header-collapse-main, .header-collapse-condense'))
+  );
+};

package/src/native/shared/events.ts

@@ -0,0 +1,14 @@
+export const CSS_MOTION_EVENTS = {
+  transitionRun: 'transitionrun',
+  transitionEnd: 'transitionend',
+  transitionCancel: 'transitioncancel',
+  animationStart: 'animationstart',
+  animationEnd: 'animationend',
+  animationCancel: 'animationcancel',
+} as const;
+
+// Ionic adapter event names. Generic DOM sources do not require this lifecycle.
+export const LIFECYCLE_WILL_ENTER = 'ionViewWillEnter';
+export const LIFECYCLE_WILL_LEAVE = 'ionViewWillLeave';
+export const LIFECYCLE_DID_ENTER = 'ionViewDidEnter';
+export const LIFECYCLE_DID_LEAVE = 'ionViewDidLeave';

package/src/native/shared/icons.ts

@@ -0,0 +1,57 @@
+export const iconSource = (svg: SVGElement, mirrored?: boolean): string | undefined => {
+  // A small, local SVG subset. Never load external content while projecting UI.
+  if (
+    svg.querySelector('script, foreignObject, image, use, animate, animateTransform, set, style, text') ||
+    /url\((?!["']?#)/.test(svg.outerHTML)
+  )
+    return undefined;
+  // Ionicons flips the wrapper, not the SVG, for directional icons in RTL.
+  if (mirrored === undefined && svg.parentElement?.matches('.icon-inner')) {
+    const transform = new DOMMatrixReadOnly(getComputedStyle(svg.parentElement).transform);
+    mirrored = transform.is2D && transform.a === -1 && transform.d === 1 && !transform.b && !transform.c && !transform.e && !transform.f;
+  }
+  const copy = svg.cloneNode(true) as SVGElement;
+  const originals = [svg, ...Array.from(svg.querySelectorAll('*'))];
+  const copies = [copy, ...Array.from(copy.querySelectorAll('*'))];
+  originals.forEach((node, index) => {
+    const style = getComputedStyle(node);
+    for (const property of ['fill', 'stroke', 'stroke-width', 'opacity', 'fill-opacity', 'stroke-opacity', 'color']) {
+      (copies[index] as SVGElement).style.setProperty(property, style.getPropertyValue(property));
+    }
+  });
+  copy.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  if (mirrored) {
+    copy.style.transform = 'scaleX(-1)';
+    copy.style.transformOrigin = 'center';
+  }
+  return new XMLSerializer().serializeToString(copy);
+};
+
+export const createIconRenderer = () => {
+  const cache = new Map<string, string>();
+  return {
+    clear: () => cache.clear(),
+    async render(source: string, width: number, height: number): Promise<string> {
+      const scale = devicePixelRatio || 1;
+      const key = `${width}:${height}:${scale}:${source}`;
+      const cached = cache.get(key);
+      if (cached) return cached;
+      const url = URL.createObjectURL(new Blob([source], { type: 'image/svg+xml' }));
+      try {
+        const image = new Image();
+        image.src = url;
+        await image.decode();
+        const canvas = document.createElement('canvas');
+        canvas.width = Math.ceil(width * scale);
+        canvas.height = Math.ceil(height * scale);
+        canvas.getContext('2d')!.drawImage(image, 0, 0, canvas.width, canvas.height);
+        const data = canvas.toDataURL('image/png').split(',')[1];
+        if (cache.size >= 128) cache.delete(cache.keys().next().value!);
+        cache.set(key, data);
+        return data;
+      } finally {
+        URL.revokeObjectURL(url);
+      }
+    },
+  };
+};