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

package/dist/controls/overlays/styles.d.ts

@@ -0,0 +1,9 @@
+export declare const sheetText: (sheets: readonly CSSStyleSheet[]) => string;
+export declare const relayStyles: (source: Document, destination: Document, overlay: HTMLElement, changed?: () => void) => {
+    destination: HTMLElement;
+    ready: Promise<void>;
+    stop: () => void;
+};
+export declare const captureRelayAppearance: (roots: Element[]) => (() => boolean);
+/** Flattening an ancestor must not remove a containing block or visual effect. */
+export declare const relayLayoutSupported: (overlay: HTMLElement) => boolean;

package/dist/controls/overlays/styles.js

@@ -0,0 +1,194 @@
+export const sheetText = (sheets) => sheets.flatMap((sheet) => Array.from(sheet.cssRules, (rule) => rule.cssText)).join('\n');
+export const relayStyles = (source, destination, overlay, changed) => {
+    const base = destination.createElement('base');
+    base.href = source.baseURI;
+    destination.head.append(base);
+    const copies = new Map();
+    const sheets = destination.createElement('style');
+    destination.head.append(sheets);
+    const sync = () => {
+        sheets.textContent = sheetText(source.adoptedStyleSheets);
+        const sources = Array.from(source.querySelectorAll('meta[name=viewport],link[rel=stylesheet],style:not([data-overlay-relay-local])'));
+        for (const [node, copy] of copies)
+            if (!sources.includes(node)) {
+                copy.remove();
+                copies.delete(node);
+            }
+        for (const node of sources) {
+            let copy = copies.get(node);
+            if (!copy) {
+                copy = node.cloneNode(true);
+                copies.set(node, copy);
+            }
+            else {
+                for (const attribute of Array.from(copy.attributes))
+                    copy.removeAttribute(attribute.name);
+                for (const attribute of Array.from(node.attributes))
+                    copy.setAttribute(attribute.name, attribute.value);
+                copy.textContent = node.textContent;
+            }
+            destination.head.append(copy);
+        }
+        destination.head.append(surface);
+    };
+    const surface = destination.createElement('style');
+    surface.textContent = 'html,body{background:transparent!important}';
+    const observers = [];
+    const mirror = (node, target, flatten = false) => {
+        let attributes = '';
+        const update = () => {
+            const next = JSON.stringify(Array.from(node.attributes, ({ name, value }) => [name, value]));
+            if (next === attributes)
+                return false;
+            attributes = next;
+            for (const attribute of Array.from(target.attributes))
+                if (!node.hasAttribute(attribute.name))
+                    target.removeAttribute(attribute.name);
+            for (const attribute of Array.from(node.attributes))
+                target.setAttribute(attribute.name, attribute.value);
+            // The popover content must not inherit the source page's rail layout.
+            if (target.localName === 'ion-app')
+                target.classList.remove('ios-theme-vertical-bars');
+            if (flatten)
+                target.style.setProperty('display', 'contents', 'important');
+            return true;
+        };
+        update();
+        const observer = new MutationObserver(() => {
+            if (update())
+                changed?.();
+        });
+        observer.observe(node, { attributes: true });
+        observers.push(observer);
+    };
+    mirror(source.documentElement, destination.documentElement);
+    mirror(source.body, destination.body);
+    const ancestors = [];
+    for (let node = overlay.parentElement; node && node !== source.body; node = node.parentElement)
+        ancestors.unshift(node);
+    let parent = destination.body;
+    for (const node of ancestors) {
+        const shell = destination.createElement(node.localName);
+        mirror(node, shell, true);
+        parent.append(shell);
+        parent = shell;
+    }
+    sync();
+    // A copied external stylesheet can still be loading when Ionic's content is
+    // ready. Do not expose an unstyled first native frame (notably button sizes).
+    const ready = Promise.all(Array.from(destination.querySelectorAll('link[rel=stylesheet]'), (link) => {
+        if (link.sheet)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            link.addEventListener('load', () => resolve(), { once: true });
+            link.addEventListener('error', () => reject(new Error('Popover stylesheet unavailable')), { once: true });
+        });
+    })).then(() => undefined);
+    const localStyle = (node) => node instanceof Element && node.matches('style[data-overlay-relay-local]');
+    const observer = new MutationObserver((records) => {
+        // Source-only projection pixels never affect the relayed content. Their
+        // preparation must not dismiss a popover which still owns its native anchor.
+        const local = (record) => {
+            const target = record.target instanceof Element ? record.target : record.target.parentElement;
+            if (target?.closest('style[data-overlay-relay-local]'))
+                return true;
+            const nodes = [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)];
+            return record.type === 'childList' && nodes.length > 0 && nodes.every(localStyle);
+        };
+        if (records.every(local))
+            return;
+        sync();
+        changed?.();
+    });
+    observer.observe(source.head, { subtree: true, childList: true, characterData: true, attributes: true });
+    observers.push(observer);
+    return { destination: parent, ready, stop: () => observers.forEach((item) => item.disconnect()) };
+};
+// Compare the live content at the same proposed size before exposing a native
+// surface. Ancestor/sibling selectors and container queries can change when
+// ancestor shells become display:contents; unsupported contexts stay on Web.
+export const captureRelayAppearance = (roots) => {
+    const properties = [
+        'display',
+        'position',
+        'box-sizing',
+        'color',
+        'background-color',
+        'background-image',
+        'background-size',
+        'background-position',
+        'box-shadow',
+        'visibility',
+        'opacity',
+        'transform',
+        'filter',
+        'overflow',
+        'text-decoration',
+        'font-family',
+        'font-size',
+        'font-weight',
+        'font-style',
+        'line-height',
+        'letter-spacing',
+        'text-align',
+        'text-transform',
+        'white-space',
+        'direction',
+        'padding-top',
+        'padding-right',
+        'padding-bottom',
+        'padding-left',
+        'margin-top',
+        'margin-right',
+        'margin-bottom',
+        'margin-left',
+        'border-top-width',
+        'border-right-width',
+        'border-bottom-width',
+        'border-left-width',
+        'border-top-color',
+        'border-radius',
+        'flex-direction',
+        'flex-wrap',
+        'justify-content',
+        'align-items',
+        'grid-template-columns',
+        'grid-template-rows',
+        'gap',
+        'width',
+        'height',
+    ];
+    const snapshots = [];
+    const values = (node) => {
+        const css = node.ownerDocument.defaultView.getComputedStyle(node);
+        return properties.map((property) => css.getPropertyValue(property));
+    };
+    const visit = (node) => {
+        if (snapshots.length >= 1000)
+            throw new Error('Popover content too complex to verify native styling');
+        snapshots.push({ node, values: values(node) });
+        Array.from(node.children).forEach(visit);
+        if (node.shadowRoot)
+            Array.from(node.shadowRoot.children)
+                .filter((child) => !child.matches('style, link'))
+                .forEach(visit);
+    };
+    roots.forEach(visit);
+    return () => snapshots.every(({ node, values: before }) => values(node).every((value, index) => {
+        return value === before[index];
+    }));
+};
+/** Flattening an ancestor must not remove a containing block or visual effect. */
+export const relayLayoutSupported = (overlay) => {
+    const win = overlay.ownerDocument.defaultView;
+    for (let node = overlay.parentElement; node; node = node.parentElement) {
+        const css = win.getComputedStyle(node);
+        if (css.containerType !== 'normal' ||
+            (css.transform !== 'none' && !new DOMMatrixReadOnly(css.transform).isIdentity) ||
+            css.perspective !== 'none' ||
+            css.filter !== 'none' ||
+            css.opacity !== '1')
+            return false;
+    }
+    return true;
+};

package/dist/controls/prehide.d.ts

@@ -0,0 +1,6 @@
+import type { VerticalControlAreaOptions } from './definitions.js';
+/** Capture toolbar placement once per routed-page epoch, before Ionic paints its transition. */
+export declare const prehideVerticalBarsToolbarSources: (doc: Document, enabled?: () => boolean, sourceRoot?: HTMLElement, options?: VerticalControlAreaOptions) => {
+    suspend: () => () => void;
+    stop: () => void;
+};

package/dist/controls/prehide.js

@@ -0,0 +1,280 @@
+import { localToolbarOption, toolbarOptions } from './shared/toolbar-options.js';
+import { modalUsesVerticalBars } from './shared/modal.js';
+import { LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE, LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE } from './shared/events.js';
+import { VERTICAL_BARS_TRANSITION_CANCELED } from '../integration/index.js';
+import { childElements, clearVerticalBarsPlacement, createVerticalBarsPageState, verticalBarsActionCandidate, verticalBarsBackCandidate, verticalBarsBackWebClass, verticalBarsOwned, isVerticalBarsToolbarActionShape, isPermanentlyExcluded, isNativeUIDisabled, prehiddenClass, prehideRootClass, rejectedClass, setVerticalBarsPlacement, syncToolbarText, } from './shared/dom.js';
+const overlays = 'ion-menu, ion-popover';
+const sourceSelector = 'ion-back-button, ion-menu-button, ion-buttons, ion-button';
+// Realm- and teardown-safe: globals such as Element/HTMLElement may be gone
+// when a queued mutation microtask or a stale listener still runs.
+const isHtmlElement = (node) => !!node && node.nodeType === 1;
+const asElement = (node) => (isHtmlElement(node) ? node : undefined);
+const backSupported = (element) => {
+    const back = element;
+    return back.icon === undefined && back.color === undefined && !!back.shadowRoot;
+};
+const eligibleBack = verticalBarsBackCandidate;
+const eligible = verticalBarsActionCandidate;
+const localPlacement = (element) => localToolbarOption(element, true);
+const selectedAction = (element, options) => {
+    if (!element.matches('ion-button, ion-menu-button'))
+        return false;
+    const explicit = localPlacement(element);
+    return explicit ?? (toolbarOptions(options, true).button && isVerticalBarsToolbarActionShape(element));
+};
+/** Capture toolbar placement once per routed-page epoch, before Ionic paints its transition. */
+export const prehideVerticalBarsToolbarSources = (doc, enabled = () => true, sourceRoot = doc.body, options = {}) => {
+    doc.documentElement.classList.toggle(prehideRootClass, enabled());
+    const scopes = new Map();
+    const owner = new WeakMap();
+    const pendingBacks = new Map();
+    const verticalBarsPages = createVerticalBarsPageState();
+    const listeners = new AbortController();
+    const root = () => sourceRoot.closest('ion-app.ios-theme-vertical-bars') ??
+        sourceRoot.querySelector('ion-app.ios-theme-vertical-bars');
+    let suspended = 0;
+    let stopped = false;
+    const routedPage = (element) => element.closest('.ion-page:not(ion-app, body)');
+    const release = (scope) => {
+        for (const [element, pending] of pendingBacks) {
+            if (pending.scope !== scope)
+                continue;
+            clearTimeout(pending.timer);
+            pendingBacks.delete(element);
+        }
+        const owned = scopes.get(scope);
+        if (!owned)
+            return;
+        owned.forEach((element) => {
+            if (owner.get(element) !== scope)
+                return;
+            owner.delete(element);
+            element.classList.remove(prehiddenClass);
+            element.classList.remove(verticalBarsBackWebClass);
+            clearVerticalBarsPlacement(element);
+        });
+        scopes.delete(scope);
+    };
+    const capture = (scope) => {
+        if (!root()?.contains(scope) || scope.closest(overlays) || !modalUsesVerticalBars(scope) || verticalBarsPages.isDeparted(scope))
+            return;
+        const owned = scopes.get(scope) ?? new Set();
+        const place = (element, rail) => {
+            if (owned.has(element))
+                return;
+            const previousScope = owner.get(element);
+            if (previousScope)
+                scopes.get(previousScope)?.delete(element);
+            owner.set(element, scope);
+            setVerticalBarsPlacement(element, rail);
+            if (element.matches('ion-back-button'))
+                element.classList.toggle(verticalBarsBackWebClass, !rail);
+            owned.add(element);
+        };
+        const sources = scope.matches('ion-back-button') ? [scope] : Array.from(scope.querySelectorAll(sourceSelector));
+        sources.forEach((element) => {
+            if (!sourceRoot.contains(element))
+                return;
+            // Shell opt-out is temporary; decide initial placement once it is lifted.
+            if (isNativeUIDisabled(element))
+                return;
+            if (!modalUsesVerticalBars(element) || element.closest(overlays) || (scope.matches('.ion-page') && routedPage(element) !== scope))
+                return;
+            if (element.matches('ion-buttons')) {
+                const children = childElements(element);
+                const actions = children.filter((child) => eligible(child) && selectedAction(child, options));
+                const group = (localPlacement(element) ?? toolbarOptions(options, true).buttonGroup) &&
+                    eligible(element) &&
+                    actions.length === children.length &&
+                    (actions.length > 1 || (actions.length === 1 && actions[0].matches('ion-menu-button')));
+                const freshGroup = !owned.has(element);
+                place(element, group);
+                children.forEach((child) => {
+                    if (!child.matches('ion-back-button'))
+                        place(child, freshGroup && actions.includes(child));
+                });
+            }
+            else if (element.matches('ion-back-button') || !element.parentElement?.matches('ion-buttons')) {
+                if (owned.has(element))
+                    return;
+                if (element.matches('ion-back-button') &&
+                    eligibleBack(element) &&
+                    element.icon === undefined &&
+                    element.color === undefined &&
+                    !element.shadowRoot &&
+                    !element.classList.contains('hydrated')) {
+                    const previousPending = pendingBacks.get(element);
+                    if (previousPending && previousPending.scope !== scope) {
+                        clearTimeout(previousPending.timer);
+                        pendingBacks.delete(element);
+                    }
+                    if (!pendingBacks.has(element)) {
+                        const timer = setTimeout(() => {
+                            if (pendingBacks.get(element)?.scope !== scope)
+                                return;
+                            pendingBacks.delete(element);
+                            // A custom element that never hydrates must remain usable on Web.
+                            place(element, false);
+                            reconcile();
+                        }, 1500);
+                        pendingBacks.set(element, { scope, timer });
+                    }
+                    return;
+                }
+                const pending = pendingBacks.get(element);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    pendingBacks.delete(element);
+                }
+                place(element, element.matches('ion-back-button')
+                    ? (localPlacement(element) ?? toolbarOptions(options, true).backButton) && eligibleBack(element) && backSupported(element)
+                    : eligible(element) && selectedAction(element, options));
+            }
+        });
+        scopes.set(scope, owned);
+    };
+    const reconcile = () => {
+        doc.documentElement.classList.toggle(prehideRootClass, enabled() && !suspended);
+        syncToolbarText(doc);
+        const verticalBars = root();
+        if (!verticalBars) {
+            Array.from(scopes.keys()).forEach(release);
+            return;
+        }
+        for (const scope of scopes.keys())
+            if (!scope.isConnected || !modalUsesVerticalBars(scope))
+                release(scope);
+        for (const [element, pending] of pendingBacks)
+            if (element.shadowRoot || element.classList.contains('hydrated'))
+                capture(pending.scope);
+        // Ionic inserts the destination as invisible before WillEnter. Hide its
+        // sources in that same mutation microtask; capture new DOM identities on active pages too.
+        verticalBars.querySelectorAll('.ion-page:not(ion-app, body, .ion-page-hidden)').forEach(capture);
+        // Root toolbars can mount after startup; each new DOM identity is captured once.
+        verticalBars.querySelectorAll(sourceSelector).forEach((element) => {
+            if (routedPage(element) || element.closest(overlays))
+                return;
+            const scope = element.closest('ion-toolbar') ?? (element.matches('ion-back-button') ? element : null);
+            if (scope)
+                capture(scope);
+        });
+        for (const owned of scopes.values()) {
+            for (const element of owned) {
+                const groupOwnsChildren = element.parentElement?.matches('ion-buttons') &&
+                    verticalBarsOwned(element.parentElement) &&
+                    childElements(element.parentElement).every((child) => verticalBarsOwned(child));
+                const hide = enabled() &&
+                    !element.closest('[data-native-ui-placement="element"]') &&
+                    !suspended &&
+                    verticalBarsOwned(element) &&
+                    !groupOwnsChildren &&
+                    element.isConnected &&
+                    !element.closest(`.${rejectedClass}`) &&
+                    !isPermanentlyExcluded(element) &&
+                    !isNativeUIDisabled(element) &&
+                    (!element.matches('ion-back-button') || backSupported(element) || !element.classList.contains('hydrated')) &&
+                    (!element.matches('ion-buttons') || childElements(element).every((child) => verticalBarsOwned(child)));
+                element.classList.toggle(prehiddenClass, hide);
+                if (element.matches('ion-back-button'))
+                    element.classList.toggle(verticalBarsBackWebClass, !hide);
+            }
+        }
+    };
+    const onWillEnter = (event) => {
+        const page = asElement(event.target);
+        if (page?.matches('.ion-page')) {
+            verticalBarsPages.lifecycle(event);
+            release(page); // Cached pages begin a new placement epoch.
+            capture(page);
+            reconcile();
+        }
+    };
+    const onPageLifecycle = (event) => {
+        verticalBarsPages.lifecycle(event);
+        if (event.type !== LIFECYCLE_DID_LEAVE)
+            return;
+        const page = asElement(event.target);
+        if (page)
+            release(page);
+    };
+    // A canceled transition keeps the leaving page active and abandons the entering one.
+    const onTransitionCanceled = (event) => {
+        const leaving = asElement(event.target);
+        if (!leaving)
+            return;
+        const entering = event.detail?.entering;
+        verticalBarsPages.cancel(entering, leaving);
+        reconcile();
+    };
+    doc.addEventListener(LIFECYCLE_WILL_ENTER, onWillEnter, { capture: true, signal: listeners.signal });
+    for (const name of [LIFECYCLE_WILL_LEAVE, LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE])
+        doc.addEventListener(name, onPageLifecycle, { capture: true, signal: listeners.signal });
+    doc.addEventListener(VERTICAL_BARS_TRANSITION_CANCELED, onTransitionCanceled, { capture: true, signal: listeners.signal });
+    doc.defaultView?.addEventListener('nativeUIRefresh', reconcile, { signal: listeners.signal });
+    reconcile();
+    const mutationRelevant = (record) => {
+        if (record.type === 'characterData')
+            return record.target.parentElement?.matches('ion-toolbar') === true;
+        if (record.type === 'childList' && asElement(record.target)?.matches('ion-toolbar'))
+            return true;
+        if (record.type === 'childList')
+            return [...Array.from(record.addedNodes), ...Array.from(record.removedNodes)].some((node) => isHtmlElement(node) &&
+                (node.matches(`${sourceSelector}, .ion-page, ion-toolbar`) || !!node.querySelector(`${sourceSelector}, .ion-page, ion-toolbar`)));
+        if (record.attributeName !== 'class')
+            return true;
+        const current = record.target.className;
+        const previous = record.oldValue ?? '';
+        const withoutOwned = (value) => value
+            .split(/\s+/)
+            .filter((name) => name && ![prehiddenClass, prehideRootClass, verticalBarsBackWebClass].includes(name))
+            .join(' ');
+        return typeof current !== 'string' || withoutOwned(previous) !== withoutOwned(current);
+    };
+    let scheduled = false;
+    const observer = new (doc.defaultView?.MutationObserver ?? MutationObserver)((records) => {
+        if (scheduled || stopped || !records.some(mutationRelevant))
+            return;
+        scheduled = true;
+        queueMicrotask(() => {
+            scheduled = false;
+            if (!stopped)
+                reconcile();
+        });
+    });
+    observer.observe(doc.documentElement, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true,
+        attributeOldValue: true,
+        attributeFilter: ['class', 'data-native-ui', 'hidden', 'inert', 'icon', 'color'],
+    });
+    return {
+        suspend: () => {
+            if (stopped)
+                return () => { };
+            suspended++;
+            doc.documentElement.classList.remove(prehideRootClass);
+            reconcile();
+            let resumed = false;
+            return () => {
+                if (resumed || stopped)
+                    return;
+                resumed = true;
+                if (--suspended === 0) {
+                    doc.documentElement.classList.add(prehideRootClass);
+                    reconcile();
+                }
+            };
+        },
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            observer.disconnect();
+            listeners.abort();
+            doc.documentElement.classList.remove(prehideRootClass);
+            Array.from(scopes.keys()).forEach(release);
+        },
+    };
+};

package/dist/controls/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { NativeUIConnection } from './shared/connection.js';
+import type { NativeUIRuntimeHandle, NativeUIRuntimeOptions, NativeUIPlugin } from './definitions.js';
+export declare const createRuntime: (doc: Document, plugin: NativeUIPlugin, options?: NativeUIRuntimeOptions, nativeVerticalBars?: () => boolean, onStop?: (cause: "failure" | "pagehide") => void, connection?: NativeUIConnection) => Promise<NativeUIRuntimeHandle & {
+    retain: (deferActivation?: (id: string) => boolean) => () => void;
+}>;