@webview-native-ui/engine 1.0.1 → 1.0.2

package/src/controls/overlays/styles.ts

@@ -0,0 +1,195 @@
+export const sheetText = (sheets: readonly CSSStyleSheet[]): string =>
+  sheets.flatMap((sheet) => Array.from(sheet.cssRules, (rule) => rule.cssText)).join('\n');
+
+export const relayStyles = (
+  source: Document,
+  destination: Document,
+  overlay: HTMLElement,
+  changed?: () => void,
+): { destination: HTMLElement; ready: Promise<void>; stop: () => void } => {
+  const base = destination.createElement('base');
+  base.href = source.baseURI;
+  destination.head.append(base);
+  const copies = new Map<Element, Element>();
+  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) as Element;
+        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: MutationObserver[] = [];
+  const mirror = (node: Element, target: HTMLElement, 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: Element[] = [];
+  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<HTMLLinkElement>('link[rel=stylesheet]'), (link) => {
+      if (link.sheet) return Promise.resolve();
+      return new Promise<void>((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) => 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: MutationRecord) => {
+      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: Element[]): (() => boolean) => {
+  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: { node: Element; values: string[] }[] = [];
+  const values = (node: Element) => {
+    const css = node.ownerDocument.defaultView!.getComputedStyle(node);
+    return properties.map((property) => css.getPropertyValue(property));
+  };
+  const visit = (node: Element) => {
+    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: HTMLElement): boolean => {
+  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/src/controls/prehide.ts

@@ -0,0 +1,285 @@
+import { localToolbarOption, toolbarOptions } from './shared/toolbar-options.js';
+import type { VerticalControlAreaOptions } from './definitions.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: unknown): node is HTMLElement => !!node && (node as Node).nodeType === 1;
+const asElement = (node: Node | EventTarget | null): HTMLElement | undefined => (isHtmlElement(node) ? node : undefined);
+const backSupported = (element: HTMLElement): boolean => {
+  const back = element as HTMLIonBackButtonElement;
+  return back.icon === undefined && back.color === undefined && !!back.shadowRoot;
+};
+const eligibleBack = verticalBarsBackCandidate;
+const eligible = verticalBarsActionCandidate;
+const localPlacement = (element: HTMLElement) => localToolbarOption(element, true);
+const selectedAction = (element: HTMLElement, options: VerticalControlAreaOptions): boolean => {
+  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: Document,
+  enabled: () => boolean = () => true,
+  sourceRoot: HTMLElement = doc.body,
+  options: VerticalControlAreaOptions = {},
+): { suspend: () => () => void; stop: () => void } => {
+  doc.documentElement.classList.toggle(prehideRootClass, enabled());
+  const scopes = new Map<HTMLElement, Set<HTMLElement>>();
+  const owner = new WeakMap<HTMLElement, HTMLElement>();
+  const pendingBacks = new Map<HTMLElement, { scope: HTMLElement; timer: ReturnType<typeof setTimeout> }>();
+  const verticalBarsPages = createVerticalBarsPageState();
+  const listeners = new AbortController();
+  const root = () =>
+    sourceRoot.closest<HTMLElement>('ion-app.ios-theme-vertical-bars') ??
+    sourceRoot.querySelector<HTMLElement>('ion-app.ios-theme-vertical-bars');
+  let suspended = 0;
+  let stopped = false;
+  const routedPage = (element: HTMLElement) => element.closest<HTMLElement>('.ion-page:not(ion-app, body)');
+  const release = (scope: HTMLElement) => {
+    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: HTMLElement) => {
+    if (!root()?.contains(scope) || scope.closest(overlays) || !modalUsesVerticalBars(scope) || verticalBarsPages.isDeparted(scope)) return;
+    const owned = scopes.get(scope) ?? new Set<HTMLElement>();
+    const place = (element: HTMLElement, rail: boolean) => {
+      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<HTMLElement>(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 as HTMLIonBackButtonElement).icon === undefined &&
+          (element as HTMLIonBackButtonElement).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<HTMLElement>('.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<HTMLElement>(sourceSelector).forEach((element) => {
+      if (routedPage(element) || element.closest(overlays)) return;
+      const scope = element.closest<HTMLElement>('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: 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: EventListener = (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: EventListener = (event) => {
+    const leaving = asElement(event.target);
+    if (!leaving) return;
+    const entering = (event as CustomEvent<{ entering?: HTMLElement }>).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: MutationRecord) => {
+    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 as Element).className;
+    const previous = record.oldValue ?? '';
+    const withoutOwned = (value: string) =>
+      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);
+    },
+  };
+};