@rdlabo/ionic-theme-ios27 0.1.0 → 0.2.1

package/dist/transition/ios.transition.js

@@ -1,389 +1,14 @@
-import { createAnimation } from '@ionic/core';
+import { createIosTransitionAnimation, shadow } from '@rdlabo/ionic-theme-utils';
 import { getIonPageElement } from './index';
 import { connectNativeUIShellTransition } from '../native-integration';
-const DURATION = 540;
-const getClonedElement = (tagName) => {
-    return document.querySelector(`${tagName}.ion-cloned-element`);
+export { shadow };
+const transitionConfig = {
+    offLeftPercent: 30,
+    getIonPageElement,
+    connectNativeUIShellTransition,
+    radius: 0,
 };
-export const shadow = (el) => {
-    return el.shadowRoot || el;
-};
-const animateFixedBackButton = (root, navEl, page, entering, interactive, otherPage) => {
-    const button = page.querySelector(':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(':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('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);
-};
-export const iosTransitionAnimation = (navEl, opts) => {
-    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 ? '33%' : '-33%';
-        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;
-        if (topPage?.querySelector(':scope > ion-header.header-translucent:not(.ios-theme-disabled, .ios26-disabled)')) {
-            const shadow = topPage.style.boxShadow;
-            rootAnimation.beforeAddWrite(() => {
-                topPage.style.boxShadow = `${isRTL ? 4 : -4}px 0 24px rgba(0, 0, 0, 0.04)`;
-            });
-            rootAnimation.afterAddWrite(() => {
-                topPage.style.boxShadow = shadow;
-            });
-        }
-        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'));
-        }
-        else {
-            enteringContentAnimation.addElement(contentEl);
-            enteringContentAnimation.addElement(headerEls);
-        }
-        rootAnimation.addAnimation(enteringContentAnimation);
-        if (backDirection) {
-            enteringContentAnimation
-                .beforeClearStyles([OPACITY])
-                .fromTo('transform', `translateX(${OFF_LEFT})`, `translateX(${CENTER})`)
-                .fromTo(OPACITY, OFF_OPACITY, 1);
-        }
-        else {
-            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)
-                    .beforeClearStyles([OPACITY])
-                    .fromTo(OPACITY, 0, 0.1);
-                enteringTransitionShadow
-                    .addElement(enteringTransitionShadowEl)
-                    .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'));
-            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'));
-            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})`);
-                enteringBackButton.fromTo(OPACITY, 0.01, 1);
-            }
-            else {
-                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)');
-                }
-                enteringBackButton.fromTo(OPACITY, 0.01, 1);
-                if (backButtonEl) {
-                    const enteringBackBtnText = createAnimation();
-                    enteringBackBtnText
-                        .addElement(shadow(backButtonEl).querySelector('.button-text'))
-                        .fromTo(`transform`, isRTL ? 'translateX(-100px)' : 'translateX(100px)', 'translateX(0px)');
-                    enteringToolBar.addAnimation(enteringBackBtnText);
-                }
-            }
-        });
-        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'));
-            }
-            else {
-                leavingContent.addElement(leavingContentEl);
-                leavingContent.addElement(leavingHeaderEls);
-            }
-            rootAnimation.addAnimation(leavingContent);
-            if (backDirection) {
-                leavingContent
-                    .beforeClearStyles([OPACITY])
-                    .fromTo('transform', `translateX(${CENTER})`, isRTL ? 'translateX(-100%)' : 'translateX(100%)');
-                const leavingPage = getIonPageElement(leavingEl);
-                rootAnimation.afterAddWrite(() => {
-                    if (rootAnimation.getDirection() === 'normal') {
-                        leavingPage.style.setProperty('display', 'none');
-                    }
-                });
-            }
-            else {
-                leavingContent.fromTo('transform', `translateX(${CENTER})`, `translateX(${OFF_LEFT})`).fromTo(OPACITY, 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)
-                        .beforeClearStyles([OPACITY])
-                        .fromTo(OPACITY, 0.1, 0);
-                    leavingTransitionShadow
-                        .addElement(leavingTransitionShadowEl)
-                        .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'));
-                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'));
-                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);
-                leavingBackButton.fromTo(OPACITY, 0.99, 0);
-                leavingToolBarButtons.fromTo(OPACITY, 0.99, 0);
-                leavingToolBarItems.fromTo(OPACITY, 0.99, 0);
-                if (backDirection) {
-                    if (!inactiveHeader) {
-                        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']);
-                    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'))
-                            .fromTo('transform', `translateX(${CENTER})`, `translateX(${(isRTL ? -124 : 124) + 'px'})`);
-                        leavingToolBar.addAnimation(leavingBackBtnText);
-                    }
-                }
-                else {
-                    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;
-    }
+export const setConfig = (config) => {
+    Object.assign(transitionConfig, config);
 };
+export const iosTransitionAnimation = createIosTransitionAnimation(transitionConfig);

package/docs/features.md

@@ -13,6 +13,8 @@ To customize the library's default styles to match your design, several CSS vari
 
 For menus, `--ios-theme-menu-background-rgb` sets the surface RGB channels (light: `225, 230, 240`; dark: `26, 31, 34`). `--ios-theme-menu-background-opacity` controls opacity and defaults to `0.96`. Both are public customization variables and can be set on `ion-menu`.
 
+Button press scaling follows `:active` with a slight overshoot. Set `--ios-theme-button-press-duration` (default: `380ms`) to customize its duration instead of the shared activated-transition duration variables.
+
 ## Liquid Glass mixin
 
 Import the SCSS files from the main package to use the liquid glass mixin.
@@ -27,7 +29,7 @@ ion-textarea label.textarea-wrapper {
 
 ## Native UI Shell (Experimental)
 
-Capacitor iOS apps can use the optional, experimental [Native UI Shell](native-ui-shell.md) to render supported fixed Ionic controls with UIKit and system Liquid Glass. Content and application logic stay in the WebView, with Ionic owning routing and page transitions. The guide explains the hybrid approach's origins in Basecamp and Capacitor, setup, supported controls and Web fallback behavior.
+Capacitor iOS apps can use the optional, experimental [Native UI Shell](https://docs.rdlabo.dev/projects/ionic-theme-ios27/docs/native-ui-shell) to render supported fixed Ionic controls with UIKit and system Liquid Glass. Content and application logic stay in the WebView, with Ionic owning routing and page transitions. The guide explains the hybrid approach's origins in Basecamp and Capacitor, setup, supported controls and Web fallback behavior.
 
 ## Selective component imports
 

package/docs/native-ui-shell.md

@@ -24,6 +24,14 @@ import { enableNativeUIShell } from '@rdlabo/ionic-theme-ios27/native';
 void enableNativeUIShell();
 ```
 
+`enableNativeUIShell()` also reads the WebView's effective top-left corner radius and applies it to page transitions. To configure only the transition without enabling native controls, call:
+
+```ts
+import { configureNativeTransition } from '@rdlabo/ionic-theme-ios27/native';
+
+await configureNativeTransition();
+```
+
 Keep the existing `navAnimation: iosTransitionAnimation` setting. No per-page registration, component list, native callback, or Swift view controller is required. Run `npx cap sync ios` after installing or updating the package. The native plugin uses Swift Package Manager (SPM). For an existing CocoaPods app, run `npx cap spm-migration-assistant` and link the generated `CapApp-SPM` package to the app target in Xcode. Build with Xcode 26 or later and Capacitor 8; native glass requires iOS 26 or later. Web, Android, SSR and older iOS keep the Web implementation.
 
 This is an opt-in feature. The ordinary package entry point does not import Capacitor, and `@capacitor/core` is an optional peer dependency. Native sources are still detected and built by Capacitor's sync when this package is installed in a Capacitor project, even if the application does not call `enableNativeUIShell()`.
@@ -122,8 +130,113 @@ console.log(shell.getStatus()); // state, projected control count, update count,
 await shell.destroy(); // restore DOM, remove native controls and release listeners/cache
 ```
 
+Projection is globally enabled by default. Limit it to selected Ionic components when an application only wants part of the native shell, or disable it globally while retaining the same configuration path:
+
+```ts
+const shell = await enableNativeUIShell({
+  enabled: true,
+  controls: {
+    tabs: true,
+  },
+});
+
+// Equivalent to leaving Native UI Shell off; all controls remain on the Web.
+const disabledShell = await enableNativeUIShell({ enabled: false });
+```
+
+Omitting `controls` enables every supported control for backward compatibility. When `controls` is present, only entries set to `true` are native-eligible. Available entries are `tabs`, `toolbar`, `segment`, and `fab`.
+
+For a custom modal or overlay that Native UI Shell cannot detect, acquire a suspension before presenting it. The resolved suspension means projected controls have returned to Web rendering. Always release it after dismissal:
+
+```ts
+const suspension = await shell.suspend();
+
+try {
+  await modal.present();
+  await modal.onDidDismiss();
+} finally {
+  await suspension.resume();
+}
+```
+
+Suspensions are nestable and `resume()` is idempotent. Native projection resumes only after every active suspension has been released, using the current DOM rather than a stale snapshot.
+
 The native material and control appearance follow the running iOS version; an iOS 26 device does not acquire iOS 27's appearance merely by installing this theme.
 
+## Native UI Shell API
+
+The generated reference below documents the handle returned by `enableNativeUIShell()`. The underlying Capacitor bridge and its control-snapshot protocol are implementation details.
+
+<docgen-index>
+
+* [`getStatus()`](#getstatus)
+* [`suspend()`](#suspend)
+* [`destroy()`](#destroy)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### getStatus()
+
+```typescript
+getStatus() => NativeUIShellStatus
+```
+
+Returns the current Web/native projection state.
+
+**Returns:** <code><a href="#nativeuishellstatus">NativeUIShellStatus</a></code>
+
+--------------------
+
+
+### suspend()
+
+```typescript
+suspend() => Promise<NativeUIShellSuspension>
+```
+
+Restores projected controls to the Web until the returned lease is resumed.
+
+**Returns:** <code>Promise&lt;<a href="#nativeuishellsuspension">NativeUIShellSuspension</a>&gt;</code>
+
+--------------------
+
+
+### destroy()
+
+```typescript
+destroy() => Promise<void>
+```
+
+Stops synchronization, restores Web controls and releases native resources.
+
+--------------------
+
+
+### Interfaces
+
+
+#### NativeUIShellStatus
+
+| Prop            | Type                                        |
+| --------------- | ------------------------------------------- |
+| **`state`**     | <code>'native' \| 'stopped' \| 'web'</code> |
+| **`projected`** | <code>number</code>                         |
+| **`updates`**   | <code>number</code>                         |
+| **`reason`**    | <code>string</code>                         |
+
+
+#### NativeUIShellSuspension
+
+| Method     | Signature                    | Description                                                                                    |
+| ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
+| **resume** | () =&gt; Promise&lt;void&gt; | Releases this suspension. Native projection resumes after all active suspensions are released. |
+
+</docgen-api>
+
 ## Source layout
 
 Each TypeScript module in [`src/native/components`](../src/native/components) declares its Ionic tag and DOM reader. `components/index.ts` combines those exports into discovery selectors and the component type. Shared DOM measurements, item data and SVG rendering live in `src/native/shared`; `runtime.ts` owns synchronization, visibility handoffs and lifecycle events.

package/ios/Sources/IonicNativeUIShellPlugin/IonicNativeUIShellPlugin.swift

@@ -8,6 +8,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
     public let jsName = "IonicNativeUIShell"
     public let pluginMethods: [CAPPluginMethod] = [
         CAPPluginMethod(name: "configure", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getWebViewMetrics", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "update", returnType: CAPPluginReturnPromise),
         CAPPluginMethod(name: "clear", returnType: CAPPluginReturnPromise)
     ]
@@ -45,6 +46,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
                     }
                 }
                 if keyboard { self.bridge?.triggerWindowJSEvent(eventName: "nativeUIShellRefresh") }
+                else if name == UIDevice.orientationDidChangeNotification { self.notifyWebViewMetricsChange() }
             })
         }
         for name in [UIApplication.didBecomeActiveNotification, UIResponder.keyboardDidHideNotification,
@@ -52,6 +54,7 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
             observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
                 if name == UIResponder.keyboardDidHideNotification { self?.keyboardVisible = false }
                 self?.bridge?.triggerWindowJSEvent(eventName: "nativeUIShellRefresh", data: name == UIApplication.didBecomeActiveNotification ? "{\"retireSearch\":true}" : "{}")
+                if name == UIApplication.didBecomeActiveNotification { self?.notifyWebViewMetricsChange() }
             })
         }
     }
@@ -60,6 +63,31 @@ public class IonicNativeUIShellPlugin: CAPPlugin, CAPBridgedPlugin, UITabBarDele
         observers.forEach(NotificationCenter.default.removeObserver)
     }
 
+    private func webViewMetrics() -> JSObject? {
+        guard #available(iOS 26.0, *), let webView = bridge?.webView else { return nil }
+        webView.layoutIfNeeded()
+        return ["radius": Double(webView.effectiveRadius(corner: .topLeft))]
+    }
+
+    private func notifyWebViewMetricsChange() {
+        guard let metrics = webViewMetrics() else { return }
+        notifyListeners("webViewMetricsChange", data: metrics)
+    }
+
+    @objc func getWebViewMetrics(_ call: CAPPluginCall) {
+        DispatchQueue.main.async { [weak self] in
+            guard #available(iOS 26.0, *) else {
+                call.resolve(["radius": 0])
+                return
+            }
+            guard let metrics = self?.webViewMetrics() else {
+                call.reject("WebView unavailable")
+                return
+            }
+            call.resolve(metrics)
+        }
+    }
+
     @objc func configure(_ call: CAPPluginCall) {
         DispatchQueue.main.async { [weak self] in
             // A new JS context starts revision numbering again (live reload / navigation).

package/node_modules/@rdlabo/ionic-theme-utils/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masahiko Sakakibara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@rdlabo/ionic-theme-utils/README.md

@@ -0,0 +1,28 @@
+# @rdlabo/ionic-theme-utils
+
+Shared, theme-neutral utilities for Rdlabo Ionic themes.
+
+TypeScript and Sass sources are exported directly. Consumers are expected to
+compile them as part of an Angular/Ionic application build.
+
+```typescript
+import { createIosTransitionAnimation, getPopoverPosition } from '@rdlabo/ionic-theme-utils';
+```
+
+```scss
+@use 'pkg:@rdlabo/ionic-theme-utils/styles/structured-list';
+```
+
+The package currently contains shared iOS transition construction, popover
+positioning, searchable tab-bar utilities, and structured-list Sass mixins.
+
+## Development
+
+```shell
+npm install
+npm run build
+npm run lint
+```
+
+Use `npm link` while developing this package together with a theme repository.
+Theme repositories should use a tagged Git dependency for reproducible installs.

package/node_modules/@rdlabo/ionic-theme-utils/dist/dom.d.ts

@@ -0,0 +1,3 @@
+export declare const getElementRoot: (el: HTMLElement, fallback?: HTMLElement) => HTMLElement | ShadowRoot;
+export declare const raf: (h: FrameRequestCallback) => any;
+//# sourceMappingURL=dom.d.ts.map

package/node_modules/@rdlabo/ionic-theme-utils/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,cAAc,GAAI,IAAI,WAAW,EAAE,WAAU,WAAgB,6BAEzE,CAAC;AAEF,eAAO,MAAM,GAAG,GAAI,GAAG,oBAAoB,QAQ1C,CAAC"}