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

package/src/controls/startup.ts

@@ -0,0 +1,74 @@
+import { createNativeUIActivation } from './activation.js';
+import type { NativeUITransport } from './transport.js';
+import type { NativeUIRuntimeOptions, NativeUIHandle, NativeUIOptions, NativeUIRuntimeHandle } from './definitions.js';
+
+export const createNativeUI = (transport: NativeUITransport) => {
+  const { enableNativeUI: activate, configureNativeTransition } = createNativeUIActivation(transport);
+  type OverlayFactory = Parameters<typeof activate>[1];
+  const handles = new WeakMap<NativeUIRuntimeHandle, NativeUIHandle>();
+
+  /** Start one shell. Partial options override defaults; markup owns individual placement. */
+  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. */
+  const enableNativeUI = (options: NativeUIOptions = {}): Promise<NativeUIHandle> => startNativeUI(options);
+
+  return { startNativeUI, enableNativeUI, configureNativeTransition };
+};

package/src/controls/transport.ts

@@ -0,0 +1,11 @@
+import type { NativeUIPlugin } from './definitions.js';
+
+/** Host bridge supplied by Capacitor, Cordova, or another embedding runtime. */
+export interface NativeUITransport {
+  readonly plugin: NativeUIPlugin;
+  getPlatform(): string;
+  isAvailable(): boolean;
+}
+export interface NativeUIListenerHandle {
+  remove(): Promise<void>;
+}

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

@@ -0,0 +1,86 @@
+import { getNativeSearchBindings, type NativeSearchBinding } from '../integration/index.js';
+import { activateProjectedElement, marker, unprojected } from './shared/dom.js';
+
+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' : '';
+    },
+  };
+};