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

package/dist/controls/html.js

@@ -0,0 +1,260 @@
+import { getProjectionState } from './shared/covered-source.js';
+import { fitsClip } from './shared/clipping.js';
+import { appendItem, createCandidate } from './shared/candidate.js';
+import { marker, unprojected, visible } from './shared/dom.js';
+/** Standard HTML sources use standard native renderers, not app-local Swift extensions. */
+export const htmlSelector = '[data-native-ui="button"], [data-native-ui="back-button"]';
+export const htmlRailSource = (element) => element.matches(htmlSelector) && element.getAttribute('data-native-ui-placement') === 'rail';
+export const readHTMLControl = (element, id, options) => {
+    if (!(options.root ?? element.ownerDocument.body).contains(element) ||
+        !element.matches(htmlSelector) ||
+        element.closest('[data-native-ui-proxy]'))
+        return;
+    // Explicit opt-in; custom elements can implement click() and expose role=button.
+    if (!element.matches('button, ion-button, [role="button"]') || !visible(element, htmlRailSource(element)))
+        return;
+    if (element.contains(element.ownerDocument.activeElement))
+        return;
+    if (!htmlRailSource(element) && !fitsClip(element))
+        return;
+    if (htmlRailSource(element) && options.verticalBars?.enabled === false)
+        return;
+    const kind = element.getAttribute('data-native-ui') === 'back-button' ? 'back-button' : 'button';
+    const candidate = createCandidate(element, kind, id, options);
+    const item = appendItem(candidate, element, id);
+    if (!item)
+        return;
+    const labelledBy = element
+        .getAttribute('aria-labelledby')
+        ?.trim()
+        .split(/\s+/)
+        .map((key) => element.ownerDocument.getElementById(key)?.textContent?.trim() ?? '')
+        .filter(Boolean)
+        .join(' ');
+    item.accessibilityLabel = labelledBy || element.getAttribute('aria-label') || item.label;
+    if (!item.accessibilityLabel)
+        return;
+    item.disabled ||= element.matches(':disabled, [disabled]') || !!element.closest('[aria-disabled="true"]');
+    if (htmlRailSource(element))
+        candidate.control.placement = 'vertical-bars';
+    return candidate;
+};
+/** A rail host is supplied and styled by the application, never by the plugin. */
+export const createHTMLWebProjection = (doc, options) => {
+    const host = options.rail?.host;
+    if (!host) {
+        let stopped = false;
+        return {
+            markForCheck: () => { },
+            getStatus: () => ({ state: stopped ? 'stopped' : 'web', projected: 0, updates: 0 }),
+            suspend: async () => ({ resume: async () => { } }),
+            destroy: async () => {
+                stopped = true;
+            },
+        };
+    }
+    const projectionState = getProjectionState(doc);
+    const { isProjectionMutation, sourcesChangedEvent, targetsChangedEvent } = projectionState;
+    const win = doc.defaultView;
+    const owned = new Map();
+    const style = doc.createElement('style');
+    style.textContent = `[data-native-ui-web-source] { visibility: hidden !important; pointer-events: none !important; }
+    [data-native-ui-proxy][data-native-ui-proxy-prepared] { position: absolute !important; }
+    [data-native-ui-proxy][data-native-ui-proxy-prepared]:not([data-native-ui-snapshot-visible]) { visibility:hidden!important; }`;
+    doc.head.append(style);
+    let frame = 0;
+    let stopped = false;
+    let suspended = 0;
+    let updates = 0;
+    const restore = (source) => {
+        const state = owned.get(source);
+        if (!state)
+            return;
+        const focused = state.clone.contains(doc.activeElement);
+        state.clone.remove();
+        if (stopped && projectionState.getTarget(source) === state.clone)
+            projectionState.deleteTarget(source);
+        source.removeAttribute('data-native-ui-web-source');
+        if (focused && source.isConnected && !source.hasAttribute(marker))
+            source.focus();
+        owned.delete(source);
+    };
+    const measure = (source, read) => {
+        const hidden = source.hasAttribute('data-native-ui-web-source');
+        if (hidden)
+            source.removeAttribute('data-native-ui-web-source');
+        try {
+            return unprojected([source], read);
+        }
+        finally {
+            if (hidden)
+                source.setAttribute('data-native-ui-web-source', '');
+        }
+    };
+    const render = () => {
+        frame = 0;
+        if (stopped)
+            return;
+        observer.disconnect();
+        observer.observe(doc.documentElement, { subtree: true, childList: true, attributes: true, characterData: true });
+        const wanted = new Set();
+        if (options.verticalBars?.enabled !== false && host?.isConnected && options.root?.isConnected) {
+            const sources = Array.from(options.root.querySelectorAll(htmlSelector));
+            let back = false;
+            for (const source of sources) {
+                // An accepted native surface owns its source and descendants. Rejected sources
+                // lose the marker and can return to the Web rail on the next render.
+                if (!htmlRailSource(source) || host.contains(source))
+                    continue;
+                const covered = projectionState.isVisible(source) ||
+                    (projectionState.owns(source) && !!owned.get(source)?.clone.hasAttribute(projectionState.imageMarker));
+                // Keep a fixed fallback host available before the first native capture.
+                const prepared = (source.hasAttribute(marker) && source.hasAttribute('data-native-ui-vertical-bars')) ||
+                    projectionState.preparedOwners.includes(source);
+                if ((suspended && !covered) || (!covered && !prepared && (source.closest(`[${marker}]`) || projectionState.owns(source))))
+                    continue;
+                // Keep the prepared target stable through coverage and native restoration.
+                // Reading a changed/disabled source here must not replace its pre-touch image.
+                const existing = owned.get(source);
+                if (covered && existing) {
+                    wanted.add(source);
+                    existing.clone.inert = true;
+                    existing.clone.setAttribute('aria-hidden', 'true');
+                    back ||= existing.clone.getAttribute('data-native-ui-proxy') === 'back-button';
+                    continue;
+                }
+                const iconRoot = source.querySelector('ion-icon')?.shadowRoot;
+                if (iconRoot)
+                    observer.observe(iconRoot, { subtree: true, childList: true, attributes: true, characterData: true });
+                const candidate = measure(source, () => readHTMLControl(source, () => 'web', options));
+                if (!candidate)
+                    continue;
+                if (candidate.control.kind === 'back-button') {
+                    if (back)
+                        continue;
+                    back = true;
+                }
+                wanted.add(source);
+                const item = candidate.control.items[0];
+                const svg = source.querySelector('svg') ?? iconRoot?.querySelector('svg');
+                const signature = JSON.stringify([item, source.innerHTML, svg?.outerHTML]);
+                let state = owned.get(source);
+                if (!state) {
+                    const clone = doc.createElement('button');
+                    clone.type = 'button';
+                    clone.setAttribute('data-native-ui-proxy', candidate.control.kind);
+                    state = { clone, aria: source.getAttribute('aria-hidden'), signature: '' };
+                    owned.set(source, state);
+                    clone.addEventListener('click', () => {
+                        const current = !stopped && !suspended && measure(source, () => readHTMLControl(source, () => 'web', options));
+                        if (options.verticalBars?.enabled === false ||
+                            !current ||
+                            !htmlRailSource(source) ||
+                            !host.isConnected ||
+                            current.control.items[0].disabled ||
+                            source.closest(`[${marker}]`) ||
+                            projectionState.owns(source))
+                            return;
+                        source.click(); // Source owns submission, custom handlers and back navigation.
+                        schedule();
+                    });
+                    clone.toggleAttribute('data-native-ui-proxy-prepared', prepared);
+                    projectionState.setTarget(source, clone);
+                    host.append(clone);
+                }
+                state.clone.toggleAttribute('data-native-ui-proxy-prepared', prepared);
+                state.clone.inert = prepared || covered;
+                if (prepared || covered)
+                    state.clone.setAttribute('aria-hidden', 'true');
+                else
+                    state.clone.removeAttribute('aria-hidden');
+                if (state.signature !== signature) {
+                    state.signature = signature;
+                    state.clone.replaceChildren();
+                    if (svg) {
+                        const icon = svg.cloneNode(true);
+                        icon.querySelectorAll('[id]').forEach((node) => node.removeAttribute('id'));
+                        icon.removeAttribute('id');
+                        for (const node of [icon, ...Array.from(icon.querySelectorAll('*'))])
+                            for (const attr of Array.from(node.attributes))
+                                if (attr.name.startsWith('on'))
+                                    node.removeAttribute(attr.name);
+                        state.clone.append(icon);
+                    }
+                    state.clone.append(doc.createTextNode(item.label));
+                    state.clone.setAttribute('aria-label', item.accessibilityLabel);
+                    state.clone.disabled = item.disabled;
+                    updates++;
+                }
+                if (!source.hasAttribute('data-native-ui-web-source'))
+                    source.setAttribute('data-native-ui-web-source', '');
+            }
+        }
+        for (const source of owned.keys())
+            if (!wanted.has(source))
+                restore(source);
+        const clones = Array.from(wanted, (source) => owned.get(source).clone);
+        const order = Array.from(host.children).filter((child) => clones.includes(child));
+        const focused = clones.find((clone) => clone === doc.activeElement);
+        clones.forEach((clone, index) => {
+            if (order[index] === clone)
+                return;
+            host.insertBefore(clone, order[index]);
+            order.splice(order.indexOf(clone), 1);
+            order.splice(index, 0, clone);
+        });
+        // Moving an existing button can blur it; retain keyboard focus across source reordering.
+        if (focused && doc.activeElement !== focused)
+            focused.focus({ preventScroll: true });
+        win.dispatchEvent(new Event(targetsChangedEvent));
+        // Ignore our own synchronous DOM writes; later application mutations still schedule a refresh.
+        observer.takeRecords();
+    };
+    const schedule = () => {
+        if (!stopped && !frame)
+            frame = win.requestAnimationFrame(render);
+    };
+    const observer = new MutationObserver((records) => {
+        if (records.some((record) => !isProjectionMutation(record)))
+            schedule();
+    });
+    win.addEventListener('resize', schedule);
+    win.addEventListener('nativeUIRefresh', schedule);
+    win.addEventListener(sourcesChangedEvent, schedule);
+    render();
+    return {
+        markForCheck: schedule,
+        getStatus: () => ({
+            state: stopped ? 'stopped' : 'web',
+            projected: [...owned.values()].filter(({ clone }) => !clone.inert).length,
+            updates,
+        }),
+        async suspend() {
+            suspended++;
+            render();
+            let resumed = false;
+            return {
+                async resume() {
+                    if (!resumed) {
+                        resumed = true;
+                        suspended--;
+                        render();
+                    }
+                },
+            };
+        },
+        async destroy() {
+            if (stopped)
+                return;
+            stopped = true;
+            observer.disconnect();
+            win.cancelAnimationFrame(frame);
+            win.removeEventListener('resize', schedule);
+            win.removeEventListener('nativeUIRefresh', schedule);
+            win.removeEventListener(sourcesChangedEvent, schedule);
+            for (const source of owned.keys())
+                restore(source);
+            style.remove();
+        },
+    };
+};

package/dist/controls/index.d.ts

@@ -0,0 +1,7 @@
+export { createNativeUI } from './startup.js';
+export { defineNativeUI } from './extensions.js';
+export { setVerticalControlAreaPlacement } from './legacy-layout.js';
+export { applyFoldStateClasses } from './foldable/fold-state.js';
+export type * from './definitions.js';
+export type * from './extensions.js';
+export type * from './transport.js';

package/dist/controls/index.js

@@ -0,0 +1,4 @@
+export { createNativeUI } from './startup.js';
+export { defineNativeUI } from './extensions.js';
+export { setVerticalControlAreaPlacement } from './legacy-layout.js';
+export { applyFoldStateClasses } from './foldable/fold-state.js';

package/dist/controls/ionic.d.ts

@@ -0,0 +1 @@
+export { createOverlayController } from './overlays/controller.js';

package/dist/controls/ionic.js

@@ -0,0 +1 @@
+export { createOverlayController } from './overlays/controller.js';

package/dist/controls/legacy-layout.d.ts

@@ -0,0 +1,7 @@
+import type { VerticalBarEdge, VerticalBarPlacement } from './definitions.js';
+/**
+ * @deprecated Use the theme setVerticalBarsLayout helper. nativeEdge is ignored; device metrics determine availability.
+ * Legacy Web layout adapter; does not report native availability.
+ * Pass `rtl` when the document direction is known; otherwise the nearest `dir` attribute is used.
+ */
+export declare const setVerticalControlAreaPlacement: (placement: VerticalBarEdge | VerticalBarPlacement, rtl?: boolean) => void;

package/dist/controls/legacy-layout.js

@@ -0,0 +1,23 @@
+const physicalVerticalBarEdge = (edge, rtl) => ((edge === 'leading') !== rtl ? 'left' : 'right');
+const elementRtl = (element) => element.closest('[dir]')?.getAttribute('dir') === 'rtl';
+/**
+ * @deprecated Use the theme setVerticalBarsLayout helper. nativeEdge is ignored; device metrics determine availability.
+ * Legacy Web layout adapter; does not report native availability.
+ * Pass `rtl` when the document direction is known; otherwise the nearest `dir` attribute is used.
+ */
+export const setVerticalControlAreaPlacement = (placement, rtl) => {
+    if (typeof document === 'undefined')
+        return;
+    const app = document.querySelector('ion-app');
+    if (!app)
+        throw new Error('Vertical Control Area requires ion-app');
+    const { edge, inset = 0 } = placement && typeof placement === 'object' ? placement : { edge: placement, inset: 0 };
+    app.removeAttribute('data-native-ui-vertical-bars-suspended');
+    app.classList.toggle('ios-theme-vertical-bars', edge !== null);
+    app.classList.toggle('ios-theme-vertical-bars-left', edge !== null && physicalVerticalBarEdge(edge, rtl ?? elementRtl(app)) === 'left');
+    if (edge && Number.isFinite(inset) && inset > 0)
+        app.style.setProperty('--ios-theme-vertical-bars-native-inset', `${inset}px`);
+    else
+        app.style.removeProperty('--ios-theme-vertical-bars-native-inset');
+    document.defaultView?.dispatchEvent(new Event('nativeUIRefresh'));
+};

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

@@ -0,0 +1,2 @@
+/** Constructed stylesheets cannot cross documents with their nodes. */
+export declare const moveContent: (content: HTMLElement[], destination: HTMLElement) => (() => void);

package/dist/controls/overlays/content.js

@@ -0,0 +1,55 @@
+import { sheetText } from './styles.js';
+/** Constructed stylesheets cannot cross documents with their nodes. */
+export const moveContent = (content, destination) => {
+    const home = content.map((element) => ({ element, parent: element.parentNode, next: element.nextSibling }));
+    const roots = [];
+    const collect = (node) => {
+        if (node.shadowRoot) {
+            roots.push({
+                root: node.shadowRoot,
+                css: sheetText(node.shadowRoot.adoptedStyleSheets),
+                sheets: [...node.shadowRoot.adoptedStyleSheets],
+            });
+            for (const child of Array.from(node.shadowRoot.children))
+                collect(child);
+        }
+        for (const child of Array.from(node.children))
+            collect(child);
+    };
+    content.forEach(collect);
+    for (const element of content)
+        destination.append(destination.ownerDocument.adoptNode(element));
+    const styles = roots
+        .filter(({ css }) => css)
+        .map(({ root, css }) => {
+        const style = destination.ownerDocument.createElement('style');
+        style.textContent = css;
+        root.append(style);
+        return style;
+    });
+    return () => {
+        styles.forEach((style) => style.remove());
+        for (const { element, parent, next } of home) {
+            const connected = element.isConnected;
+            parent.ownerDocument.adoptNode(element);
+            // Ionic may already have destroyed the Angular component on dismiss.
+            if (connected)
+                parent.insertBefore(element, next?.parentNode === parent ? next : null);
+        }
+        for (const { root, css, sheets } of roots) {
+            // WebKit re-associates adopted sheets with the new document across
+            // adoptNode, so they may no longer match this root; fall back to the
+            // inline copy instead of aborting the remaining restore.
+            try {
+                root.adoptedStyleSheets = sheets;
+            }
+            catch {
+                if (css) {
+                    const style = root.ownerDocument.createElement('style');
+                    style.textContent = css;
+                    root.append(style);
+                }
+            }
+        }
+    };
+};

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

@@ -0,0 +1,7 @@
+import type { NativeUIOptions, NativeUIPlugin } from '../definitions.js';
+import type { NativeUIConnection } from '../shared/connection.js';
+/** Ionic owns lifecycle and dismissal; only one overlay is relayed at a time. */
+export declare const createOverlayController: (doc: Document, plugin: NativeUIPlugin, options: NativeUIOptions, retainProjection: (deferActivation?: (id: string) => boolean) => () => void, nativeVerticalBars: () => boolean, connection?: NativeUIConnection) => Promise<{
+    suspend(): Promise<() => void>;
+    destroy(): Promise<void>;
+}>;