@rdlabo/capacitor-native-ui 0.0.0-stage → 2.0.0-1

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);
+      }
+    },
+  };
+};

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('nativeUIRefresh'));
+    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('nativeUIRefresh', 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/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/native/shared/toolbar-options.ts

@@ -0,0 +1,49 @@
+import { modalUsesVerticalBars } from './modal';
+import type { VerticalControlAreaOptions } from '../definitions';
+import { controlDefault } from './control-options';
+import { childElements, inFixedToolbar, isExcluded, isNativeUIDisabled } from './dom';
+
+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')),
+    )
+  );
+};
+
+export const inVerticalToolbarLayout = (element: HTMLElement): boolean =>
+  !element.closest('ion-menu, ion-popover') && modalUsesVerticalBars(element) && !!element.closest('ion-app.ios-theme-vertical-bars');

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

@@ -0,0 +1,80 @@
+import type { Frame } from '../definitions';
+
+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();
+  Object.assign(clone.style, {
+    position: 'absolute',
+    left: `${frame.x - origin.left}px`,
+    top: `${frame.y - origin.top}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: Frame, items: Map<HTMLElement, Frame>): (() => 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);
+  const box = (rect: Frame, 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;`;
+  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/native/startup.ts

@@ -0,0 +1,68 @@
+import { enableNativeUI as activate } from './activation';
+import type { NativeUIRuntimeOptions, NativeUIHandle, NativeUIOptions, NativeUIRuntimeHandle } from './definitions';
+
+type OverlayFactory = Parameters<typeof activate>[1];
+const handles = new WeakMap<NativeUIRuntimeHandle, NativeUIHandle>();
+
+/** Start one shell. Partial options override defaults; markup owns individual placement. */
+export const startNativeUI = async (input: NativeUIOptions = {}, overlayFactory?: OverlayFactory): Promise<NativeUIHandle> => {
+  const root = input.root ?? (typeof document === 'undefined' ? undefined : document.body);
+  const bars = { enabled: true, ...input.verticalBars };
+  const host = bars.placement?.webHost;
+  if (root && (!root.isConnected || root.ownerDocument !== document))
+    throw new Error('Native UI requires a connected root in the current document');
+  if (host && (!host.isConnected || host.ownerDocument !== document || root?.contains(host) || host.contains(root!)))
+    throw new Error('The Web rail host must be connected in the current document and outside the source root');
+  const options: NativeUIRuntimeOptions = {
+    ...input,
+    root,
+    source: 'auto',
+    verticalBars: bars,
+    rail: host ? { host, edge: bars.placement?.edge === 'leading' ? 'left' : 'right' } : undefined,
+  };
+  const runtime = await activate(options, overlayFactory);
+  const existing = handles.get(runtime);
+  if (existing) return existing;
+  let stopped = false;
+  let queue = Promise.resolve();
+  const change = (enabled: boolean) => {
+    const operation = queue.then(async () => {
+      if (stopped) throw new Error('Native UI has been destroyed');
+      if (bars.enabled === enabled) return;
+      // Retire both surfaces before changing ownership. Resume also waits for native reconciliation.
+      const lease = await runtime.suspend();
+      try {
+        if (stopped) throw new Error('Native UI has been destroyed');
+        bars.enabled = enabled;
+        root?.ownerDocument.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+      } finally {
+        await lease.resume();
+      }
+    });
+    queue = operation.catch(() => {});
+    return operation;
+  };
+  let destruction: Promise<void> | undefined;
+  const destroy = runtime.destroy.bind(runtime);
+  const handle: NativeUIHandle = {
+    markForCheck: runtime.markForCheck.bind(runtime),
+    getStatus: runtime.getStatus.bind(runtime),
+    suspend: runtime.suspend.bind(runtime),
+    enableVerticalControlArea: () => change(true),
+    disableVerticalControlArea: () => change(false),
+    destroy() {
+      if (!destruction) {
+        stopped = true;
+        // Reserve native teardown immediately, preserving the shared startup queue.
+        destruction = destroy();
+      }
+      return destruction;
+    },
+  };
+  const managed = Object.assign(runtime, handle);
+  handles.set(runtime, managed);
+  return managed;
+};
+
+/** Enable the shared standard shell without loading the optional Ionic overlay adapter. */
+export const enableNativeUI = (options: NativeUIOptions = {}): Promise<NativeUIHandle> => startNativeUI(options);

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

@@ -0,0 +1,86 @@
+import { getNativeSearchBindings, type NativeSearchBinding } from '../native-integration';
+import { activateProjectedElement, marker, unprojected } from './shared/dom';
+
+export const searchProjectionClass = 'ios-theme-vertical-bars-search-projection';
+
+/** Web counterpart of the system search button above the vertical tabs, or at the rail bottom without visible tabs. */
+export const createVerticalBarsWebSearch = (doc: Document, eligible: (element: HTMLElement) => boolean, refresh: () => void) => {
+  let binding: NativeSearchBinding | undefined;
+  let projection: HTMLIonFabButtonElement | undefined;
+  let container: HTMLIonFabElement | undefined;
+  const iconObserver = new MutationObserver(refresh);
+  let previousAriaHidden: string | null = null;
+  const restore = (retire?: (surface: HTMLElement) => void) => {
+    iconObserver.disconnect();
+    if (container) {
+      if (retire) retire(container);
+      else container.remove();
+    }
+    container = undefined;
+    projection = undefined;
+    if (binding) {
+      binding.trigger.removeAttribute(marker);
+      if (previousAriaHidden === null) binding.trigger.removeAttribute('aria-hidden');
+      else binding.trigger.setAttribute('aria-hidden', previousAriaHidden);
+    }
+    binding = undefined;
+  };
+  return {
+    restore,
+    get surface() {
+      return container;
+    },
+    get source() {
+      return binding?.trigger;
+    },
+    update(root: HTMLElement) {
+      const next = unprojected(binding ? [binding.trigger] : [], () =>
+        getNativeSearchBindings(doc).find(({ trigger, footer }) => eligible(trigger) && eligible(footer)),
+      );
+      if (next !== binding || container?.parentElement !== root) restore();
+      if (!next) return;
+      if (!projection) {
+        binding = next;
+        previousAriaHidden = next.trigger.getAttribute('aria-hidden');
+        projection = next.trigger.cloneNode(true) as HTMLIonFabButtonElement;
+        for (const name of ['id', 'slot', marker, 'aria-hidden', 'style']) projection.removeAttribute(name);
+        container = doc.createElement('ion-fab');
+        container.setAttribute('mode', (next.trigger as HTMLIonFabButtonElement).mode ?? 'ios');
+        container.classList.add(searchProjectionClass, 'ion-cloned-element');
+        projection.addEventListener(
+          'click',
+          (event) => {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            activateProjectedElement(next.trigger);
+          },
+          { capture: true },
+        );
+        container.append(projection);
+        root.append(container);
+        next.trigger.setAttribute(marker, '');
+        next.trigger.setAttribute('aria-hidden', 'true');
+      }
+      projection.setAttribute(
+        'aria-label',
+        next.trigger.getAttribute('aria-label') ?? next.footer.querySelector('ion-searchbar')?.getAttribute('aria-label') ?? 'Search',
+      );
+      const sourceIcon = next.trigger.querySelector('ion-icon');
+      const icon = projection.querySelector('ion-icon');
+      if (sourceIcon?.shadowRoot) iconObserver.observe(sourceIcon.shadowRoot, { subtree: true, childList: true, attributes: true });
+      if (sourceIcon && icon) {
+        icon.icon = sourceIcon.icon;
+        icon.name = sourceIcon.name;
+        icon.src = sourceIcon.src;
+      }
+      container!.hidden = next.trigger.style.pointerEvents === 'none';
+      projection.disabled = (next.trigger as HTMLIonFabButtonElement).disabled;
+      const bounds = next.tabBar.getBoundingClientRect();
+      const tabs = bounds.width > 0 && bounds.height > 0 && getComputedStyle(next.tabBar).visibility === 'visible' ? bounds : undefined;
+      container!.style.left = tabs ? `${tabs.left + (tabs.width - 46) / 2}px` : '';
+      container!.style.top = tabs ? `${tabs.top - 56}px` : '';
+      container!.style.right = tabs ? 'auto' : '';
+      container!.style.bottom = tabs ? 'auto' : '';
+    },
+  };
+};