@rdlabo/ionic-theme-ios27 0.1.0 → 0.2.1

package/node_modules/@rdlabo/ionic-theme-utils/src/transition/ios.transition.ts

@@ -0,0 +1,542 @@
+import type { Animation } from '@ionic/core';
+import { createAnimation } from '@ionic/core';
+
+/** Options consumed by the shared iOS page transition animation. */
+export interface IosTransitionAnimationOptions {
+  enteringEl: HTMLElement;
+  leavingEl?: HTMLElement;
+  direction?: string;
+  duration?: number;
+  easing?: string;
+  progressCallback?: (ani: Animation | undefined) => void;
+}
+
+/** Theme-specific knobs for {@link createIosTransitionAnimation}. */
+export interface IosTransitionAnimationConfig {
+  /**
+   * Previous-page retreat as a positive percent of the viewport width.
+   * ios26 uses 30; ios27 uses 33.
+   */
+  offLeftPercent: number;
+  /** Radius applied to the foreground page while transitioning. */
+  radius?: number;
+  /** Resolves the ion-page (or fallback) element for a leaving view. */
+  getIonPageElement: (element: HTMLElement) => Element;
+  /**
+   * Optional hook invoked after the root animation is fully composed
+   * (e.g. ios27 `connectNativeUIShellTransition`).
+   */
+  connectNativeUIShellTransition?: (animation: Animation, entering: HTMLElement, leaving?: HTMLElement) => void;
+}
+
+const DURATION = 540;
+
+const getClonedElement = <T extends HTMLIonBackButtonElement | HTMLIonTitleElement>(tagName: string) => {
+  return document.querySelector<T>(`${tagName}.ion-cloned-element`);
+};
+
+export const shadow = <T extends Element>(el: T): ShadowRoot | T => {
+  return el.shadowRoot || el;
+};
+
+const animateFixedBackButton = (
+  root: Animation,
+  navEl: HTMLElement,
+  page: HTMLElement,
+  entering: boolean,
+  interactive: boolean,
+  otherPage?: HTMLElement,
+) => {
+  const button = page.querySelector<HTMLIonBackButtonElement>(
+    ':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled) ion-back-button:not(.ios-theme-disabled, .ios26-disabled)',
+  );
+  if (!button || button.offsetWidth === 0) {
+    return;
+  }
+
+  const otherButton = otherPage?.querySelector<HTMLIonBackButtonElement>(
+    ':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled) ion-back-button:not(.ios-theme-disabled, .ios26-disabled)',
+  );
+  const persistent = !!otherButton && otherButton.offsetWidth > 0;
+  const buttons = [button, ...(persistent ? [otherButton!] : [])].map((element) => ({
+    element,
+    visibility: element.style.visibility,
+  }));
+  const rect = button.getBoundingClientRect();
+  const width = button.offsetWidth;
+  const height = button.offsetHeight;
+  const clone = getClonedElement<HTMLIonBackButtonElement>('ion-back-button');
+  if (!clone) {
+    return;
+  }
+  const cloneParent = clone.parentNode!;
+  const cloneNextSibling = clone.nextSibling;
+  const cloneStyle = clone.getAttribute('style');
+  clone.icon = button.icon;
+  clone.text = button.text;
+  clone.mode = button.mode;
+  clone.color = button.color;
+  clone.disabled = button.disabled;
+  const icon = shadow(clone).querySelector('ion-icon');
+  const animation = createAnimation().addElement(clone);
+  const fadeStart = !entering && interactive ? 0.8 : 0.4;
+  const fadeEnd = entering ? 0.96 : interactive ? 1 : 0.95;
+  if (persistent) {
+    animation.fromTo('transform', 'scale(1)', 'scale(1)').fromTo('opacity', 1, 1);
+  } else if (entering) {
+    animation.keyframes([
+      { offset: 0, transform: 'scale(1.2)', opacity: 0 },
+      { offset: fadeStart, transform: 'scale(1.2)', opacity: 0 },
+      { offset: 0.65, transform: 'scale(1.12)', opacity: 0.15 },
+      { offset: 0.9, transform: 'scale(1.02)', opacity: 0.75 },
+      { offset: fadeEnd, transform: 'scale(1)', opacity: 1 },
+      { offset: 1, transform: 'scale(1)', opacity: 1 },
+    ]);
+  } else {
+    animation.keyframes([
+      { offset: 0, transform: 'scale(1)', opacity: 1 },
+      { offset: fadeStart, transform: 'scale(1)', opacity: 1 },
+      { offset: fadeEnd, transform: 'scale(1.2)', opacity: 0 },
+      { offset: 1, transform: 'scale(1.2)', opacity: 0 },
+    ]);
+  }
+  if (icon && !persistent) {
+    const from = entering ? 'blur(4px)' : 'blur(0px)';
+    const to = entering ? 'blur(0px)' : 'blur(4px)';
+    animation.addAnimation(
+      createAnimation()
+        .addElement(icon)
+        .keyframes([
+          { offset: 0, filter: from },
+          { offset: fadeStart, filter: from },
+          { offset: fadeEnd, filter: to },
+          { offset: 1, filter: to },
+        ]),
+    );
+  }
+  root.beforeAddWrite(() => {
+    Object.assign(clone.style, {
+      position: 'fixed',
+      left: `${rect.left + (rect.width - width) / 2}px`,
+      top: `${rect.top + (rect.height - height) / 2}px`,
+      width: `${width}px`,
+      height: `${height}px`,
+      margin: '0',
+      pointerEvents: 'none',
+      visibility: 'visible',
+      display: getComputedStyle(button).display,
+      zIndex: '1000',
+    });
+    navEl.appendChild(clone);
+    buttons.forEach(({ element }) => (element.style.visibility = 'hidden'));
+  });
+  root.afterAddWrite(() => {
+    buttons.forEach(({ element, visibility }) => (element.style.visibility = visibility));
+    cloneParent.insertBefore(clone, cloneNextSibling);
+    if (cloneStyle === null) {
+      clone.removeAttribute('style');
+    } else {
+      clone.setAttribute('style', cloneStyle);
+    }
+  });
+  root.addAnimation(animation);
+};
+
+/**
+ * Builds an `iosTransitionAnimation` function parameterized by theme config
+ * (OFF_LEFT percent and an optional native-shell hook).
+ */
+export const createIosTransitionAnimation = <TOpts extends IosTransitionAnimationOptions>(
+  config: IosTransitionAnimationConfig,
+): ((navEl: HTMLElement, opts: TOpts) => Animation) => {
+  const { offLeftPercent, getIonPageElement, connectNativeUIShellTransition } = config;
+
+  return (navEl: HTMLElement, opts: TOpts): Animation => {
+    try {
+      const EASING = 'cubic-bezier(0.32,0.72,0,1)';
+      const OPACITY = 'opacity';
+      const TRANSFORM = 'transform';
+      const CENTER = '0%';
+      const OFF_OPACITY = 0.8;
+
+      const isRTL = navEl.ownerDocument.dir === 'rtl';
+      const OFF_RIGHT = isRTL ? '-99.5%' : '99.5%';
+      const OFF_LEFT = isRTL ? `${offLeftPercent}%` : `-${offLeftPercent}%`;
+
+      const enteringEl = opts.enteringEl;
+      const leavingEl = opts.leavingEl;
+
+      const backDirection = opts.direction === 'back';
+      const contentEl = enteringEl.querySelector(':scope > ion-content');
+      const headerEls = enteringEl.querySelectorAll(':scope > ion-header > *:not(ion-toolbar), :scope > ion-footer > *');
+      const enteringToolBarEls = enteringEl.querySelectorAll(':scope > ion-header > ion-toolbar');
+
+      const rootAnimation = createAnimation();
+      const enteringContentAnimation = createAnimation();
+
+      rootAnimation
+        .addElement(enteringEl)
+        .duration((opts.duration ?? 0) || DURATION)
+        .easing(opts.easing || EASING)
+        .fill('both')
+        .beforeRemoveClass('ion-page-invisible');
+
+      const topPage = backDirection ? leavingEl : enteringEl;
+      const translucentTop = topPage?.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)');
+      if (topPage && translucentTop) {
+        // UIKit dims the opaque page underneath, including its header, with 10% black.
+        const shade = navEl.ownerDocument.createElement('div');
+        shade.className = 'ios-transition-shade';
+        shade.setAttribute('aria-hidden', 'true');
+        const clipPath = topPage.style.clipPath;
+        const corner = config.radius ?? 0;
+        Object.assign(shade.style, {
+          position: 'absolute',
+          inset: '0',
+          zIndex: topPage.style.zIndex,
+          pointerEvents: 'none',
+          background: 'rgba(0, 0, 0, 0.1)',
+        });
+        rootAnimation.beforeAddWrite(() => {
+          topPage.before(shade);
+          if (corner > 0) {
+            topPage.style.clipPath = `inset(0 round ${corner}px)`;
+          }
+        });
+        rootAnimation.afterAddWrite(() => {
+          shade.remove();
+          topPage.style.clipPath = clipPath;
+        });
+        rootAnimation.addAnimation(
+          createAnimation()
+            .addElement(shade)
+            .fromTo(OPACITY, backDirection ? 1 : 0, backDirection ? 0 : 1),
+        );
+      }
+
+      if (leavingEl && navEl !== null && navEl !== undefined) {
+        const navDecorAnimation = createAnimation();
+        navDecorAnimation.addElement(navEl);
+        rootAnimation.addAnimation(navDecorAnimation);
+      }
+
+      if (enteringEl.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
+        enteringContentAnimation.addElement(enteringEl);
+      } else if (!contentEl && enteringToolBarEls.length === 0 && headerEls.length === 0) {
+        enteringContentAnimation.addElement(enteringEl.querySelector(':scope > .ion-page, :scope > ion-nav, :scope > ion-tabs')!); // REVIEW
+      } else {
+        enteringContentAnimation.addElement(contentEl!); // REVIEW
+        enteringContentAnimation.addElement(headerEls);
+      }
+
+      rootAnimation.addAnimation(enteringContentAnimation);
+
+      if (backDirection) {
+        enteringContentAnimation
+          .beforeClearStyles([OPACITY])
+          .fromTo('transform', `translateX(${OFF_LEFT})`, `translateX(${CENTER})`)
+          .fromTo(OPACITY, translucentTop ? 1 : OFF_OPACITY, 1);
+      } else {
+        // entering content, forward direction
+        enteringContentAnimation.beforeClearStyles([OPACITY]).fromTo('transform', `translateX(${OFF_RIGHT})`, `translateX(${CENTER})`);
+      }
+
+      if (contentEl && !enteringEl.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
+        const enteringTransitionEffectEl = shadow(contentEl).querySelector('.transition-effect');
+        if (enteringTransitionEffectEl) {
+          const enteringTransitionCoverEl = enteringTransitionEffectEl.querySelector('.transition-cover');
+          const enteringTransitionShadowEl = enteringTransitionEffectEl.querySelector('.transition-shadow');
+
+          const enteringTransitionEffect = createAnimation();
+          const enteringTransitionCover = createAnimation();
+          const enteringTransitionShadow = createAnimation();
+
+          enteringTransitionEffect
+            .addElement(enteringTransitionEffectEl)
+            .beforeStyles({ opacity: '1', display: 'block' })
+            .afterStyles({ opacity: '', display: '' });
+
+          enteringTransitionCover
+            .addElement(enteringTransitionCoverEl!) // REVIEW
+            .beforeClearStyles([OPACITY])
+            .fromTo(OPACITY, 0, 0.1);
+
+          enteringTransitionShadow
+            .addElement(enteringTransitionShadowEl!) // REVIEW
+            .beforeClearStyles([OPACITY])
+            .fromTo(OPACITY, 0.03, 0.7);
+
+          enteringTransitionEffect.addAnimation([enteringTransitionCover, enteringTransitionShadow]);
+          enteringContentAnimation.addAnimation([enteringTransitionEffect]);
+        }
+      }
+
+      if (topPage) {
+        animateFixedBackButton(
+          rootAnimation,
+          navEl,
+          topPage,
+          !backDirection,
+          opts.progressCallback !== undefined,
+          backDirection ? enteringEl : leavingEl,
+        );
+      }
+
+      const enteringContentHasLargeTitle = enteringEl.querySelector('ion-header.header-collapse-condense');
+
+      enteringToolBarEls.forEach((enteringToolBarEl) => {
+        if (enteringToolBarEl.closest('ion-header')?.matches('.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
+          return;
+        }
+        const enteringToolBar = createAnimation();
+        enteringToolBar.addElement(enteringToolBarEl);
+        rootAnimation.addAnimation(enteringToolBar);
+
+        const enteringTitle = createAnimation();
+        enteringTitle.addElement(enteringToolBarEl.querySelector('ion-title')!); // REVIEW
+
+        const enteringToolBarButtons = createAnimation();
+        const buttons = Array.from(enteringToolBarEl.querySelectorAll('ion-buttons,[menuToggle]'));
+
+        const parentHeader = enteringToolBarEl.closest('ion-header');
+        const inactiveHeader = parentHeader?.classList.contains('header-collapse-condense-inactive');
+
+        let buttonsToAnimate;
+        if (backDirection) {
+          buttonsToAnimate = buttons.filter((button) => {
+            const isCollapseButton = button.classList.contains('buttons-collapse');
+            return (isCollapseButton && !inactiveHeader) || !isCollapseButton;
+          });
+        } else {
+          buttonsToAnimate = buttons.filter((button) => !button.classList.contains('buttons-collapse'));
+        }
+
+        enteringToolBarButtons.addElement(buttonsToAnimate);
+
+        const enteringToolBarItems = createAnimation();
+        enteringToolBarItems.addElement(enteringToolBarEl.querySelectorAll(':scope > *:not(ion-title):not(ion-buttons):not([menuToggle])'));
+
+        const enteringToolBarBg = createAnimation();
+        enteringToolBarBg.addElement(shadow(enteringToolBarEl).querySelector('.toolbar-background')!); // REVIEW
+
+        const enteringBackButton = createAnimation();
+        const backButtonEl = enteringToolBarEl.querySelector('ion-back-button');
+
+        if (backButtonEl) {
+          enteringBackButton.addElement(backButtonEl);
+        }
+
+        enteringToolBar.addAnimation([enteringTitle, enteringToolBarButtons, enteringToolBarItems, enteringToolBarBg, enteringBackButton]);
+        enteringToolBarButtons.fromTo(OPACITY, 0.01, 1);
+        enteringToolBarItems.fromTo(OPACITY, 0.01, 1);
+
+        if (backDirection) {
+          if (!inactiveHeader) {
+            enteringTitle.fromTo('transform', `translateX(${OFF_LEFT})`, `translateX(${CENTER})`).fromTo(OPACITY, 0.01, 1);
+          }
+
+          enteringToolBarItems.fromTo('transform', `translateX(${OFF_LEFT})`, `translateX(${CENTER})`);
+
+          // back direction, entering page has a back button
+          enteringBackButton.fromTo(OPACITY, 0.01, 1);
+        } else {
+          // entering toolbar, forward direction
+          if (!enteringContentHasLargeTitle) {
+            enteringTitle.fromTo('transform', `translateX(${OFF_RIGHT})`, `translateX(${CENTER})`).fromTo(OPACITY, 0.01, 1);
+          }
+
+          enteringToolBarItems.fromTo('transform', `translateX(${OFF_RIGHT})`, `translateX(${CENTER})`);
+          enteringToolBarBg.beforeClearStyles([OPACITY, 'transform']);
+
+          const translucentHeader = parentHeader?.translucent;
+          if (!translucentHeader) {
+            enteringToolBarBg.fromTo(OPACITY, 0.01, 'var(--opacity)');
+          } else {
+            enteringToolBarBg.fromTo('transform', isRTL ? 'translateX(-100%)' : 'translateX(100%)', 'translateX(0px)');
+          }
+
+          // forward direction, entering page has a back button
+          enteringBackButton.fromTo(OPACITY, 0.01, 1);
+
+          if (backButtonEl) {
+            const enteringBackBtnText = createAnimation();
+            enteringBackBtnText
+              .addElement(shadow(backButtonEl).querySelector('.button-text')!) // REVIEW
+              .fromTo(`transform`, isRTL ? 'translateX(-100px)' : 'translateX(100px)', 'translateX(0px)');
+
+            enteringToolBar.addAnimation(enteringBackBtnText);
+          }
+        }
+      });
+
+      // setup leaving view
+      if (leavingEl) {
+        const leavingContent = createAnimation();
+        const leavingContentEl = leavingEl.querySelector(':scope > ion-content');
+        const leavingToolBarEls = leavingEl.querySelectorAll(':scope > ion-header > ion-toolbar');
+        const leavingHeaderEls = leavingEl.querySelectorAll(':scope > ion-header > *:not(ion-toolbar), :scope > ion-footer > *');
+
+        if (leavingEl.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
+          leavingContent.addElement(leavingEl);
+        } else if (!leavingContentEl && leavingToolBarEls.length === 0 && leavingHeaderEls.length === 0) {
+          leavingContent.addElement(leavingEl.querySelector(':scope > .ion-page, :scope > ion-nav, :scope > ion-tabs')!); // REVIEW
+        } else {
+          leavingContent.addElement(leavingContentEl!); // REVIEW
+          leavingContent.addElement(leavingHeaderEls);
+        }
+
+        rootAnimation.addAnimation(leavingContent);
+
+        if (backDirection) {
+          // leaving content, back direction
+          leavingContent
+            .beforeClearStyles([OPACITY])
+            .fromTo('transform', `translateX(${CENTER})`, isRTL ? 'translateX(-100%)' : 'translateX(100%)');
+
+          const leavingPage = getIonPageElement(leavingEl) as HTMLElement;
+          rootAnimation.afterAddWrite(() => {
+            if (rootAnimation.getDirection() === 'normal') {
+              leavingPage.style.setProperty('display', 'none');
+            }
+          });
+        } else {
+          // leaving content, forward direction
+          leavingContent
+            .fromTo('transform', `translateX(${CENTER})`, `translateX(${OFF_LEFT})`)
+            .fromTo(OPACITY, 1, translucentTop ? 1 : OFF_OPACITY);
+        }
+
+        if (
+          leavingContentEl &&
+          !leavingEl.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')
+        ) {
+          const leavingTransitionEffectEl = shadow(leavingContentEl).querySelector('.transition-effect');
+
+          if (leavingTransitionEffectEl) {
+            const leavingTransitionCoverEl = leavingTransitionEffectEl.querySelector('.transition-cover');
+            const leavingTransitionShadowEl = leavingTransitionEffectEl.querySelector('.transition-shadow');
+
+            const leavingTransitionEffect = createAnimation();
+            const leavingTransitionCover = createAnimation();
+            const leavingTransitionShadow = createAnimation();
+
+            leavingTransitionEffect
+              .addElement(leavingTransitionEffectEl)
+              .beforeStyles({ opacity: '1', display: 'block' })
+              .afterStyles({ opacity: '', display: '' });
+
+            leavingTransitionCover
+              .addElement(leavingTransitionCoverEl!) // REVIEW
+              .beforeClearStyles([OPACITY])
+              .fromTo(OPACITY, 0.1, 0);
+
+            leavingTransitionShadow
+              .addElement(leavingTransitionShadowEl!) // REVIEW
+              .beforeClearStyles([OPACITY])
+              .fromTo(OPACITY, 0.7, 0.03);
+
+            leavingTransitionEffect.addAnimation([leavingTransitionCover, leavingTransitionShadow]);
+            leavingContent.addAnimation([leavingTransitionEffect]);
+          }
+        }
+
+        leavingToolBarEls.forEach((leavingToolBarEl) => {
+          if (leavingToolBarEl.closest('ion-header')?.matches('.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
+            return;
+          }
+          const leavingToolBar = createAnimation();
+          leavingToolBar.addElement(leavingToolBarEl);
+
+          const leavingTitle = createAnimation();
+          leavingTitle.addElement(leavingToolBarEl.querySelector('ion-title')!); // REVIEW
+
+          const leavingToolBarButtons = createAnimation();
+          const buttons = leavingToolBarEl.querySelectorAll('ion-buttons,[menuToggle]');
+
+          const parentHeader = leavingToolBarEl.closest('ion-header');
+          const inactiveHeader = parentHeader?.classList.contains('header-collapse-condense-inactive');
+
+          const buttonsToAnimate = Array.from(buttons).filter((button) => {
+            const isCollapseButton = button.classList.contains('buttons-collapse');
+            return (isCollapseButton && !inactiveHeader) || !isCollapseButton;
+          });
+
+          leavingToolBarButtons.addElement(buttonsToAnimate);
+
+          const leavingToolBarItems = createAnimation();
+          const leavingToolBarItemEls = leavingToolBarEl.querySelectorAll(':scope > *:not(ion-title):not(ion-buttons):not([menuToggle])');
+          if (leavingToolBarItemEls.length > 0) {
+            leavingToolBarItems.addElement(leavingToolBarItemEls);
+          }
+
+          const leavingToolBarBg = createAnimation();
+          leavingToolBarBg.addElement(shadow(leavingToolBarEl).querySelector('.toolbar-background')!); // REVIEW
+
+          const leavingBackButton = createAnimation();
+          const backButtonEl = leavingToolBarEl.querySelector('ion-back-button');
+          if (backButtonEl) {
+            leavingBackButton.addElement(backButtonEl);
+          }
+
+          leavingToolBar.addAnimation([leavingTitle, leavingToolBarButtons, leavingToolBarItems, leavingBackButton, leavingToolBarBg]);
+          rootAnimation.addAnimation(leavingToolBar);
+
+          // fade out leaving toolbar items
+          leavingBackButton.fromTo(OPACITY, 0.99, 0);
+
+          leavingToolBarButtons.fromTo(OPACITY, 0.99, 0);
+          leavingToolBarItems.fromTo(OPACITY, 0.99, 0);
+
+          if (backDirection) {
+            if (!inactiveHeader) {
+              // leaving toolbar, back direction
+              leavingTitle
+                .fromTo('transform', `translateX(${CENTER})`, isRTL ? 'translateX(-100%)' : 'translateX(100%)')
+                .fromTo(OPACITY, 0.99, 0);
+            }
+
+            leavingToolBarItems.fromTo('transform', `translateX(${CENTER})`, isRTL ? 'translateX(-100%)' : 'translateX(100%)');
+            leavingToolBarBg.beforeClearStyles([OPACITY, 'transform']);
+            // leaving toolbar, back direction, and there's no entering toolbar
+            // should just slide out, no fading out
+            const translucentHeader = parentHeader?.translucent;
+            if (!translucentHeader) {
+              leavingToolBarBg.fromTo(OPACITY, 'var(--opacity)', 0);
+            } else {
+              leavingToolBarBg.fromTo('transform', 'translateX(0px)', isRTL ? 'translateX(-100%)' : 'translateX(100%)');
+            }
+
+            if (backButtonEl) {
+              const leavingBackBtnText = createAnimation();
+              leavingBackBtnText
+                .addElement(shadow(backButtonEl).querySelector('.button-text')!) // REVIEW
+                .fromTo('transform', `translateX(${CENTER})`, `translateX(${(isRTL ? -124 : 124) + 'px'})`);
+              leavingToolBar.addAnimation(leavingBackBtnText);
+            }
+          } else {
+            // leaving toolbar, forward direction
+            if (!inactiveHeader) {
+              leavingTitle
+                .fromTo('transform', `translateX(${CENTER})`, `translateX(${OFF_LEFT})`)
+                .fromTo(OPACITY, 0.99, 0)
+                .afterClearStyles([TRANSFORM, OPACITY]);
+            }
+
+            leavingToolBarItems
+              .fromTo('transform', `translateX(${CENTER})`, `translateX(${OFF_LEFT})`)
+              .afterClearStyles([TRANSFORM, OPACITY]);
+
+            leavingBackButton.afterClearStyles([OPACITY]);
+            leavingTitle.afterClearStyles([OPACITY]);
+            leavingToolBarButtons.afterClearStyles([OPACITY]);
+          }
+        });
+      }
+
+      connectNativeUIShellTransition?.(rootAnimation, enteringEl, leavingEl);
+      return rootAnimation;
+    } catch (err) {
+      throw err;
+    }
+  };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rdlabo/ionic-theme-ios27",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "iOS27 Theme for Ionic Framework",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -27,9 +27,10 @@
     "Package.swift"
   ],
   "scripts": {
-    "build": "npm run build:css && npm run build:ts",
-    "build:css": "rm -rf dist/css && sass src/styles:dist/css --style=compressed --no-source-map",
+    "build": "npm run docgen && npm run build:css && npm run build:ts",
+    "build:css": "rm -rf dist/css && sass src/styles:dist/css --style=compressed --no-source-map --pkg-importer=node",
     "build:ts": "tsc",
+    "docgen": "docgen --project tsconfig.docgen.json --api NativeUIShellHandle --output-readme docs/native-ui-shell.md",
     "build:demo": "npm run build && cd demo && npm install && npm run build -- --configuration=production",
     "lint": "prettier --check \"./**/*.{scss,ts}\" &&  prettier --parser angular --check \"./**/*.html\"",
     "fmt": "prettier --write \"./**/*.{scss,ts}\" &&  prettier --parser angular --write \"./**/*.html\"",
@@ -53,9 +54,16 @@
     "url": "https://github.com/rdlabo-dev/ionic-theme-ios27/issues"
   },
   "homepage": "https://docs.rdlabo.dev/projects/ionic-theme-ios27",
+  "dependencies": {
+    "@rdlabo/ionic-theme-utils": "git+https://github.com/rdlabo-dev/ionic-theme-utils.git#66eb2fccca10646ebfccdfb3b6c2f3b4c9b00bf6"
+  },
+  "bundleDependencies": [
+    "@rdlabo/ionic-theme-utils"
+  ],
   "devDependencies": {
     "@capacitor/core": "^8.5.2",
     "@ionic/angular": "^9.0.0",
+    "@rdlabo/capacitor-docgen": "^0.4.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.1",
     "np": "^10.2.0",
@@ -65,8 +73,8 @@
     "wrangler": "^4.125.0"
   },
   "peerDependencies": {
-    "@ionic/core": ">=8.8.1 <10",
-    "@capacitor/core": ">=8.0.0 <9"
+    "@capacitor/core": ">=8.0.0 <9",
+    "@ionic/core": ">=8.8.1 <10"
   },
   "peerDependenciesMeta": {
     "@capacitor/core": {

package/src/index.ts

@@ -1,8 +1,10 @@
 import { registeredEffect } from './sheets-of-glass/interfaces';
 import { registerEffect } from './sheets-of-glass';
 export * from './sheets-of-glass/interfaces';
-export { iosEnterAnimation as popoverEnterAnimation } from './popover/animations/ios.enter';
-export { iosLeaveAnimation as popoverLeaveAnimation } from './popover/animations/ios.leave';
+export {
+  iosPopoverEnterAnimation as popoverEnterAnimation,
+  iosPopoverLeaveAnimation as popoverLeaveAnimation,
+} from '@rdlabo/ionic-theme-utils';
 export * from './tab-bar-searchable';
 export * from './searchbar';
 export * from './transition/ios.transition';

package/src/native/definitions.ts

@@ -10,11 +10,38 @@ export interface NativeUIShellStatus {
   reason?: string;
 }
 
+export interface NativeUIShellOptions {
+  /** Enables Native UI Shell globally. Defaults to `true`. */
+  enabled?: boolean;
+  /** Controls eligible for native projection. Omit to enable every control; when present, only `true` controls are enabled. */
+  controls?: NativeUIShellControls;
+}
+
+export interface NativeUIShellControls {
+  /** Projects tab bars and their native search presentation. */
+  tabs?: boolean;
+  /** Projects toolbar buttons, including back and menu buttons. */
+  toolbar?: boolean;
+  /** Projects segments. */
+  segment?: boolean;
+  /** Projects floating action buttons. */
+  fab?: boolean;
+}
+
 export interface NativeUIShellHandle {
+  /** Returns the current Web/native projection state. */
   getStatus(): NativeUIShellStatus;
+  /** Restores projected controls to the Web until the returned lease is resumed. */
+  suspend(): Promise<NativeUIShellSuspension>;
+  /** Stops synchronization, restores Web controls and releases native resources. */
   destroy(): Promise<void>;
 }
 
+export interface NativeUIShellSuspension {
+  /** Releases this suspension. Native projection resumes after all active suspensions are released. */
+  resume(): Promise<void>;
+}
+
 export interface Frame {
   x: number;
   y: number;
@@ -98,10 +125,17 @@ export interface ShellActivation {
   sequence: number;
 }
 
+export interface WebViewMetrics {
+  /** The WebView's effective top-left corner radius in points, or `0` when unavailable. */
+  radius: number;
+}
+
 export interface NativeUIShellPlugin {
   configure(): Promise<{ supported: boolean }>;
+  getWebViewMetrics(): Promise<WebViewMetrics>;
   update(snapshot: ShellSnapshot): Promise<{ revision: number; rejectedSearches?: string[]; rejectedControls?: string[] }>;
   clear(options: { revision: number }): Promise<void>;
   addListener(name: 'activate', listener: (event: ShellActivation) => void): Promise<PluginListenerHandle>;
   addListener(name: 'search', listener: (event: ShellSearchEvent) => void): Promise<PluginListenerHandle>;
+  addListener(name: 'webViewMetricsChange', listener: (event: WebViewMetrics) => void): Promise<PluginListenerHandle>;
 }