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

package/src/controls/shared/bridge.ts

@@ -0,0 +1,18 @@
+import type { NativeUIListenerHandle as PluginListenerHandle } from '../transport.js';
+
+// 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/controls/shared/candidate.ts

@@ -0,0 +1,163 @@
+import type { NativeUIControl, NativeUIItem, NativeUIControlKind, NativeUIComponent, VerticalControlAreaOptions } from '../definitions.js';
+import { frame, isDark, isVerticalBarsSource, text, visible } from './dom.js';
+import { iconSource, type createIconRenderer } from './icons.js';
+
+export interface Candidate {
+  scrollElement?: HTMLElement;
+  assets?: { signature: string; render(renderer: ReturnType<typeof createIconRenderer>): Promise<void> };
+  buttonProjection?: 'system' | 'source';
+  buttonDefaultFill?: 'solid' | null;
+  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.ionic?.verticalBars?.buttonProjection ?? 'system',
+    buttonDefaultFill: options.ionic?.verticalBars?.buttonDefaultFill === 'solid' ? 'solid' : null,
+    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:not([data-native-ui-projection-node]), 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/controls/shared/clipping.ts

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

package/src/controls/shared/connection.ts

@@ -0,0 +1,105 @@
+import type { NativeUIListenerHandle as PluginListenerHandle } from '../transport.js';
+import type { NativeUIConnectionState, NativeUIPlugin } from '../definitions.js';
+import { bounded, boundedListener } from './bridge.js';
+
+type Check = (state: NativeUIConnectionState, restored: boolean, requestedAt: number) => void | Promise<void>;
+type Failure = (error: unknown) => void | Promise<void>;
+const failureLimit = 3;
+
+type Registration = { name: string; callback: (event: never) => void; handle?: PluginListenerHandle };
+
+/** One connection check for the shell, independent of projection retention. */
+export const createNativeConnection = (doc: Document, plugin: NativeUIPlugin) => {
+  const registrations = new Set<Registration>();
+  const checks = new Set<Check>();
+  const failures = new Map<Check, Failure>();
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout>;
+  let session: string | undefined;
+  let failed = false;
+  let consecutiveFailures = 0;
+  const install = async (registration: Registration) => {
+    const add = plugin.addListener as (name: string, callback: (event: never) => void) => Promise<PluginListenerHandle>;
+    const handle = await boundedListener(add.call(plugin, registration.name, registration.callback));
+    if (stopped || !registrations.has(registration)) await bounded(handle.remove());
+    else registration.handle = handle;
+  };
+  const listen = (async (name: string, callback: (event: never) => void) => {
+    const registration: Registration = { name, callback };
+    registrations.add(registration);
+    try {
+      await install(registration);
+    } catch (error) {
+      registrations.delete(registration);
+      throw error;
+    }
+    return {
+      async remove() {
+        registrations.delete(registration);
+        await registration.handle?.remove();
+      },
+    };
+  }) as NativeUIPlugin['addListener'];
+  const check = async () => {
+    if (stopped) return;
+    if (!doc.hidden) {
+      const requestedAt = doc.defaultView!.performance.now();
+      const registered = Array.from(registrations);
+      const observed = Array.from(checks);
+      try {
+        const state = await bounded(plugin.getConnectionState());
+        if (stopped) return;
+        let restored = failed || (session !== undefined && session !== state.session);
+        session = state.session;
+        for (const registration of registered) {
+          if (state.listeners.includes(registration.name) || !registrations.has(registration)) continue;
+          // Remove our previous callback before installing another; never replay events.
+          await bounded(Promise.resolve(registration.handle?.remove()));
+          if (stopped || !registrations.has(registration)) continue;
+          await install(registration);
+          restored = true;
+        }
+        if (stopped) return;
+        for (const callback of observed) {
+          if (checks.has(callback)) await callback(state, restored, requestedAt);
+          if (stopped) return;
+        }
+        failed = false;
+        consecutiveFailures = 0;
+      } catch (error) {
+        if (stopped) return;
+        // A later successful handshake repairs subscriptions and resynchronizes
+        // current state. A timeout ends this logical check, not the underlying request.
+        failed = true;
+        if (++consecutiveFailures >= failureLimit) {
+          for (const callback of observed) {
+            if (checks.has(callback)) await failures.get(callback)?.(error);
+            if (stopped) return;
+          }
+        }
+      }
+    }
+    if (!stopped) timer = setTimeout(() => void check(), 1000);
+  };
+  return {
+    listen,
+    observe(callback: Check, failure?: Failure) {
+      checks.add(callback);
+      if (failure) failures.set(callback, failure);
+      return () => {
+        checks.delete(callback);
+        failures.delete(callback);
+      };
+    },
+    start() {
+      timer = setTimeout(() => void check(), 1000);
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(timer);
+      checks.clear();
+      failures.clear();
+    },
+  };
+};
+export type NativeUIConnection = ReturnType<typeof createNativeConnection>;

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

@@ -0,0 +1,20 @@
+import type { NativeUIControls, NativeUIOptions } from '../definitions.js';
+
+/** Resolve one default without changing discovery, explicit selection, or placement. */
+export const controlDefault = (options: NativeUIOptions, kind: keyof NativeUIControls, vertical: boolean): boolean => {
+  const controls = options.controls;
+  const value = typeof controls === 'object' ? controls[kind] : controls;
+  if (value === undefined || value === true) return true;
+  if (value === false) return false;
+  return value === (vertical ? 'verticalOnly' : 'horizontalOnly');
+};
+
+export const controlSelected = (
+  element: HTMLElement,
+  options: NativeUIOptions,
+  kind: keyof NativeUIControls,
+  vertical: boolean,
+): boolean => {
+  const local = element.getAttribute(vertical ? 'data-vertical-bars' : 'data-horizontal-bars');
+  return local === 'true' ? true : local === 'false' ? false : controlDefault(options, kind, vertical);
+};

package/src/controls/shared/covered-snapshot.ts

@@ -0,0 +1,52 @@
+import { createWebProjectionSurface } from '../../index.js';
+import type { NativeUIPlugin } from '../definitions.js';
+import { getProjectionState } from './covered-source.js';
+
+/** Ionic supplies source ownership and proxy placement; Engine owns image handoff. */
+export const createCoveredSnapshots = async (
+  doc: Document,
+  plugin: NativeUIPlugin,
+  listen: NativeUIPlugin['addListener'],
+  callbacks: { wake: () => void; blocked: () => boolean; modal?: HTMLIonModalElement; revision?: () => number },
+) => {
+  const state = getProjectionState(doc);
+  const { modal, wake, blocked, revision } = callbacks;
+  const projection = await createWebProjectionSurface(
+    {
+      send: (request) => plugin.coveredSnapshot!(request),
+      listen: (listener) => listen('snapshotInteraction', listener),
+    },
+    {
+      namespace: 'native-ui',
+      target: ({ element: source, control }) => {
+        const proxy = state.getTarget(source);
+        return control.placement === 'vertical-bars' &&
+          (proxy || source.matches('ion-button, ion-buttons, ion-back-button, ion-menu-button'))
+          ? proxy
+          : source;
+      },
+      canRelocate: (target) => target.matches('.ion-cloned-element, [data-native-ui-proxy]'),
+      wake,
+      blocked,
+      revision,
+      transient: !!modal,
+      eligible: (source) =>
+        modal
+          ? source.element.closest('ion-modal') === modal && source.control.placement === 'vertical-bars'
+          : !source.element.closest('ion-modal'),
+      current: (sources) => !modal || sources.every((source) => source.closest('ion-modal') === modal),
+    },
+  );
+  const unregister = state.register(projection);
+  const destroy = projection.destroy;
+  return Object.assign(projection, {
+    async destroy() {
+      try {
+        await destroy();
+      } finally {
+        unregister();
+      }
+    },
+  });
+};
+export type CoveredSnapshots = Awaited<ReturnType<typeof createCoveredSnapshots>>;

package/src/controls/shared/covered-source.ts

@@ -0,0 +1,78 @@
+import type { WebProjectionBatch } from '../../index.js';
+
+/** Ionic's cross-surface ownership and source/proxy mapping, not a projection DOM scope. */
+const states = new WeakMap<Document, NativeUIProjectionState>();
+const createState = () => {
+  const managers = new Set<WebProjectionBatch>();
+  const nativeOwners = new Set<(source: HTMLElement) => boolean>();
+  const targets = new WeakMap<HTMLElement, HTMLElement>();
+  const imageMarker = 'data-native-ui-snapshot';
+  const collect = (key: 'owners' | 'visibleOwners' | 'preparedOwners') => [...new Set([...managers].flatMap((manager) => manager[key]))];
+  return {
+    imageMarker,
+    nativeOwns: (source: HTMLElement) => [...nativeOwners].some((owns) => owns(source)),
+    registerNativeOwner(owns: (source: HTMLElement) => boolean) {
+      nativeOwners.add(owns);
+      return () => nativeOwners.delete(owns);
+    },
+    get snapshotsEnabled() {
+      return managers.size > 0;
+    },
+    sourcesChangedEvent: 'native-ui:sources-change',
+    targetsChangedEvent: 'native-ui:targets-change',
+    register(manager: WebProjectionBatch) {
+      managers.add(manager);
+      return () => managers.delete(manager);
+    },
+    get owners(): readonly HTMLElement[] {
+      return collect('owners');
+    },
+    get visibleOwners(): readonly HTMLElement[] {
+      return collect('visibleOwners');
+    },
+    get preparedOwners(): readonly HTMLElement[] {
+      return collect('preparedOwners');
+    },
+    owns: (element: HTMLElement) => collect('owners').some((owner) => owner === element || owner.contains(element)),
+    isVisible: (element: HTMLElement) => collect('visibleOwners').some((owner) => owner === element || owner.contains(element)),
+    getTarget: (source: HTMLElement) => targets.get(source),
+    setTarget: (source: HTMLElement, target: HTMLElement) => {
+      targets.set(source, target);
+    },
+    deleteTarget: (source: HTMLElement) => targets.delete(source),
+    isProjectionMutation(record: MutationRecord) {
+      const target = record.target instanceof Element ? record.target : record.target.parentElement;
+      if (target?.closest('[data-native-ui-projection-node]')) return true;
+      if (target?.closest('.ion-cloned-element, [data-native-ui-proxy]')) return true;
+      if (
+        record.type === 'attributes' &&
+        [
+          imageMarker,
+          'data-native-ui-proxy-prepared',
+          'data-native-ui-snapshot-prepared',
+          'data-native-ui-snapshot-source',
+          'data-native-ui-snapshot-visible',
+          'data-native-ui-snapshot-content',
+          'data-native-ui-snapshot-positioned',
+        ].includes(record.attributeName ?? '')
+      )
+        return true;
+      const image = (node: Node) =>
+        node instanceof Element &&
+        node.matches(
+          `style[${imageMarker}], style[data-native-ui-snapshot-base], [data-native-ui-proxy-prepared], [data-native-ui-snapshot-prepared], [data-native-ui-projection-node]`,
+        );
+      const nodes = [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)];
+      return image(record.target) || (record.type === 'childList' && nodes.length > 0 && nodes.every(image));
+    },
+  };
+};
+export type NativeUIProjectionState = ReturnType<typeof createState>;
+export const getProjectionState = (doc: Document): NativeUIProjectionState => {
+  let state = states.get(doc);
+  if (!state) {
+    state = createState();
+    states.set(doc, state);
+  }
+  return state;
+};

package/src/controls/shared/crossfade.ts

@@ -0,0 +1,70 @@
+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);
+      // Instant handoffs must not force layout before retiring an outgoing tab.
+      if (reduced.matches || instant || !element.isConnected) {
+        if (previous) finish(element, previous);
+        element.removeAttribute(fadeMarker);
+        return;
+      }
+      const current = Number(win.getComputedStyle(element).opacity);
+      previous?.cancel();
+      active.delete(element);
+      // Measure the Web appearance after lifting ownership concealment.
+      element.setAttribute(fadeMarker, '');
+      const opacity = Number(win.getComputedStyle(element).opacity);
+      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);
+    },
+    finish: cancelAll,
+    async settled() {
+      await Promise.all(Array.from(active.values(), (animation) => animation.finished.catch(() => {})));
+    },
+    destroy() {
+      reduced.removeEventListener('change', cancelAll);
+      cancelAll();
+    },
+  };
+  return api;
+};

package/src/controls/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] : []));
+  };
+};