@rdlabo/capacitor-native-ui 0.0.0-stage → 1.2.1

package/src/native/prehide.ts

@@ -0,0 +1,285 @@
+import { localToolbarOption, toolbarOptions } from './shared/toolbar-options';
+import type { VerticalControlAreaOptions } from './definitions';
+import { modalUsesVerticalBars } from './shared/modal';
+import { LIFECYCLE_DID_ENTER, LIFECYCLE_DID_LEAVE, LIFECYCLE_WILL_ENTER, LIFECYCLE_WILL_LEAVE } from './shared/events';
+import { VERTICAL_BARS_TRANSITION_CANCELED } from '../native-integration';
+import {
+  childElements,
+  clearVerticalBarsPlacement,
+  createVerticalBarsPageState,
+  verticalBarsActionCandidate,
+  verticalBarsBackCandidate,
+  verticalBarsBackWebClass,
+  verticalBarsOwned,
+  isVerticalBarsToolbarActionShape,
+  isPermanentlyExcluded,
+  isNativeUIDisabled,
+  prehiddenClass,
+  prehideRootClass,
+  rejectedClass,
+  setVerticalBarsPlacement,
+  syncToolbarText,
+} from './shared/dom';
+
+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).buttons) &&
+          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);
+    },
+  };
+};