@rdlabo/ionic-theme-ios27 0.1.0-beta.pr154.shac3e35365120e → 0.1.0

package/dist/popover/callout-surface.js

@@ -0,0 +1,44 @@
+export const createCalloutSurface = (root, width, height, side, center) => {
+    const inset = 32;
+    const x = inset;
+    const y = inset;
+    const right = x + width;
+    const bottom = y + height;
+    const radius = Math.max(0, Math.min(34, width / 2, height / 2, (side === 'left' || side === 'right' ? height : width) / 2 - 17));
+    const point = (u, v) => {
+        switch (side) {
+            case 'top':
+                return `${x + center - 17 + u} ${y - 13 + v}`;
+            case 'right':
+                return `${right + 13 - v} ${y + center - 17 + u}`;
+            case 'bottom':
+                return `${x + center + 17 - u} ${bottom + 13 - v}`;
+            case 'left':
+                return `${x - 13 + v} ${y + center + 17 - u}`;
+        }
+    };
+    const arrow = `L ${point(0, 13)} C ${point(3, 13)} ${point(4.5, 12)} ${point(6.5, 10)} L ${point(14.5, 1.5)} C ${point(16, -0.5)} ${point(18, -0.5)} ${point(19.5, 1.5)} L ${point(27.5, 10)} C ${point(29.5, 12)} ${point(31, 13)} ${point(34, 13)}`;
+    const path = `M ${x + radius} ${y} ${side === 'top' ? arrow : ''}
+    L ${right - radius} ${y} A ${radius} ${radius} 0 0 1 ${right} ${y + radius} ${side === 'right' ? arrow : ''}
+    L ${right} ${bottom - radius} A ${radius} ${radius} 0 0 1 ${right - radius} ${bottom} ${side === 'bottom' ? arrow : ''}
+    L ${x + radius} ${bottom} A ${radius} ${radius} 0 0 1 ${x} ${bottom - radius} ${side === 'left' ? arrow : ''}
+    L ${x} ${y + radius} A ${radius} ${radius} 0 0 1 ${x + radius} ${y} Z`;
+    const svg = (body) => `url("data:image/svg+xml,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="${width + inset * 2}" height="${height + inset * 2}">${body}</svg>`)}")`;
+    const fill = svg(`<path d="${path}" fill="white"/>`);
+    const stroke = svg(`<path d="${path}" fill="none" stroke="white" stroke-width="0.5"/>`);
+    const shadow = svg(`<defs><filter id="s" x="-50%" y="-100%" width="200%" height="300%"><feGaussianBlur stdDeviation="4"/><feOffset dy="2"/><feComposite in2="SourceGraphic" operator="out"/></filter></defs><path d="${path}" fill="white" filter="url(#s)"/>`);
+    const wrapper = root.querySelector('.popover-wrapper');
+    return [
+        ['callout-shadow', shadow],
+        ['callout-glass', fill],
+        ['callout-border', stroke],
+    ].map(([part, mask]) => {
+        const element = document.createElement('div');
+        element.setAttribute('part', part);
+        element.className = 'ios-theme-callout-layer';
+        element.setAttribute('aria-hidden', 'true');
+        element.style.cssText = `position:absolute;pointer-events:none;z-index:9;width:${width + inset * 2}px;height:${height + inset * 2}px;mask-image:${mask};-webkit-mask-image:${mask};mask-repeat:no-repeat;`;
+        wrapper.append(element);
+        return element;
+    });
+};

package/dist/sheets-of-glass/index.js

@@ -262,10 +262,11 @@ export const registerEffect = (targetElement, effectTagName, selectedClassName,
             stopTabPress();
             moveAnimation.destroy();
             moveAnimation = undefined;
+            const tabs = Array.from(targetElement.querySelectorAll(effectTagName)).filter((tab) => tab.offsetWidth > 0);
             const releasing = createTabBarReleaseAnimation(effectElement, currentTouchedElement, tapElapsed !== undefined && tapElapsed < 200
                 ? {
                     elapsed: tapElapsed,
-                    distance: Math.abs(currentTouchedElement.offsetLeft - selectedElementBeforeGesture.offsetLeft) / currentTouchedElement.offsetWidth,
+                    distance: Math.abs(tabs.indexOf(currentTouchedElement) - tabs.indexOf(selectedElementBeforeGesture)),
                 }
                 : undefined);
             currentTouchedElement.classList.remove('ion-activated');

package/dist/transition/ios.transition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ios.transition.d.ts","sourceRoot":"","sources":["../../src/transition/ios.transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAYjD,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,OAAO,EAAE,IAAI,CAAC,KAAG,UAAU,GAAG,CAE9D,CAAC;AAmkBF,eAAO,MAAM,sBAAsB,GAAI,OAAO,WAAW,EAAE,MAAM,iBAAiB,KAAG,SA4WpF,CAAC"}
+{"version":3,"file":"ios.transition.d.ts","sourceRoot":"","sources":["../../src/transition/ios.transition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAUjD,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,OAAO,EAAE,IAAI,CAAC,KAAG,UAAU,GAAG,CAE9D,CAAC;AAyGF,eAAO,MAAM,sBAAsB,GAAI,OAAO,WAAW,EAAE,MAAM,iBAAiB,KAAG,SA4WpF,CAAC"}

package/dist/transition/ios.transition.js

@@ -99,228 +99,6 @@ const animateFixedBackButton = (root, navEl, page, entering, interactive, otherP
     });
     root.addAnimation(animation);
 };
-const getLargeTitle = (refEl) => {
-    const tabs = refEl.tagName === 'ION-TABS' ? refEl : refEl.querySelector('ion-tabs');
-    const query = 'ion-content ion-header:not(.header-collapse-condense-inactive) ion-title.title-large';
-    if (tabs != null) {
-        const activeTab = tabs.querySelector('ion-tab:not(.tab-hidden), .ion-page:not(.ion-page-hidden)');
-        return activeTab != null ? activeTab.querySelector(query) : null;
-    }
-    return refEl.querySelector(query);
-};
-const getBackButton = (refEl, backDirection) => {
-    const tabs = refEl.tagName === 'ION-TABS' ? refEl : refEl.querySelector('ion-tabs');
-    let buttonsList = [];
-    if (tabs != null) {
-        const activeTab = tabs.querySelector('ion-tab:not(.tab-hidden), .ion-page:not(.ion-page-hidden)');
-        if (activeTab != null) {
-            buttonsList = activeTab.querySelectorAll('ion-buttons');
-        }
-    }
-    else {
-        buttonsList = refEl.querySelectorAll('ion-buttons');
-    }
-    for (const buttons of buttonsList) {
-        const parentHeader = buttons.closest('ion-header');
-        const activeHeader = parentHeader && !parentHeader.classList.contains('header-collapse-condense-inactive');
-        const backButton = buttons.querySelector('ion-back-button');
-        const buttonsCollapse = buttons.classList.contains('buttons-collapse');
-        const startSlot = buttons.slot === 'start' || buttons.slot === '';
-        if (backButton !== null && startSlot && ((buttonsCollapse && activeHeader && backDirection) || !buttonsCollapse)) {
-            return backButton;
-        }
-    }
-    return null;
-};
-const createLargeTitleTransition = (rootAnimation, rtl, backDirection, enteringEl, leavingEl) => {
-    const enteringBackButton = getBackButton(enteringEl, backDirection);
-    const leavingLargeTitle = getLargeTitle(leavingEl);
-    const enteringLargeTitle = getLargeTitle(enteringEl);
-    const leavingBackButton = getBackButton(leavingEl, backDirection);
-    const shouldAnimationForward = enteringBackButton !== null && leavingLargeTitle !== null && !backDirection;
-    const shouldAnimationBackward = enteringLargeTitle !== null && leavingBackButton !== null && backDirection;
-    if (shouldAnimationForward) {
-        const leavingLargeTitleBox = leavingLargeTitle.getBoundingClientRect();
-        const enteringBackButtonBox = enteringBackButton.getBoundingClientRect();
-        const enteringBackButtonTextEl = shadow(enteringBackButton).querySelector('.button-text');
-        const enteringBackButtonTextBox = enteringBackButtonTextEl?.getBoundingClientRect();
-        const leavingLargeTitleTextEl = shadow(leavingLargeTitle).querySelector('.toolbar-title');
-        const leavingLargeTitleTextBox = leavingLargeTitleTextEl.getBoundingClientRect();
-        animateLargeTitle(rootAnimation, rtl, backDirection, leavingLargeTitle, leavingLargeTitleBox, leavingLargeTitleTextBox, enteringBackButtonBox, enteringBackButtonTextEl, enteringBackButtonTextBox);
-    }
-    else if (shouldAnimationBackward) {
-        const enteringLargeTitleBox = enteringLargeTitle.getBoundingClientRect();
-        const leavingBackButtonBox = leavingBackButton.getBoundingClientRect();
-        const leavingBackButtonTextEl = shadow(leavingBackButton).querySelector('.button-text');
-        const leavingBackButtonTextBox = leavingBackButtonTextEl?.getBoundingClientRect();
-        const enteringLargeTitleTextEl = shadow(enteringLargeTitle).querySelector('.toolbar-title');
-        const enteringLargeTitleTextBox = enteringLargeTitleTextEl.getBoundingClientRect();
-        animateLargeTitle(rootAnimation, rtl, backDirection, enteringLargeTitle, enteringLargeTitleBox, enteringLargeTitleTextBox, leavingBackButtonBox, leavingBackButtonTextEl, leavingBackButtonTextBox);
-    }
-    return {
-        forward: shouldAnimationForward,
-        backward: shouldAnimationBackward,
-    };
-};
-const animateBackButton = (rootAnimation, rtl, backDirection, backButtonEl, backButtonBox, backButtonTextEl, backButtonTextBox, largeTitleEl, largeTitleTextBox) => {
-    const BACK_BUTTON_START_OFFSET = rtl ? `calc(100% - ${backButtonBox.right + 4}px)` : `${backButtonBox.left - 4}px`;
-    const TEXT_ORIGIN_X = rtl ? 'right' : 'left';
-    const ICON_ORIGIN_X = rtl ? 'left' : 'right';
-    const CONTAINER_ORIGIN_X = rtl ? 'right' : 'left';
-    let WIDTH_SCALE = 1;
-    let HEIGHT_SCALE = 1;
-    let TEXT_START_SCALE = `scale(${HEIGHT_SCALE})`;
-    const TEXT_END_SCALE = 'scale(1)';
-    if (backButtonTextEl && backButtonTextBox) {
-        const doTitleAndButtonTextsMatch = backButtonTextEl.textContent?.trim() === largeTitleEl.textContent?.trim();
-        WIDTH_SCALE = largeTitleTextBox.width / backButtonTextBox.width;
-        HEIGHT_SCALE = (largeTitleTextBox.height - LARGE_TITLE_SIZE_OFFSET) / backButtonTextBox.height;
-        TEXT_START_SCALE = doTitleAndButtonTextsMatch ? `scale(${WIDTH_SCALE}, ${HEIGHT_SCALE})` : `scale(${HEIGHT_SCALE})`;
-    }
-    const backButtonIconEl = shadow(backButtonEl).querySelector('ion-icon');
-    const backButtonIconBox = backButtonIconEl.getBoundingClientRect();
-    const CONTAINER_START_TRANSLATE_X = rtl
-        ? `${backButtonIconBox.width / 2 - (backButtonIconBox.right - backButtonBox.right)}px`
-        : `${backButtonBox.left - backButtonIconBox.width / 2}px`;
-    const CONTAINER_END_TRANSLATE_X = rtl ? `-${window.innerWidth - backButtonBox.right}px` : `${backButtonBox.left}px`;
-    const CONTAINER_START_TRANSLATE_Y = `${largeTitleTextBox.top}px`;
-    const CONTAINER_END_TRANSLATE_Y = `${backButtonBox.top}px`;
-    const FORWARD_CONTAINER_KEYFRAMES = [
-        { offset: 0, transform: `translate3d(${CONTAINER_START_TRANSLATE_X}, ${CONTAINER_START_TRANSLATE_Y}, 0)` },
-        { offset: 1, transform: `translate3d(${CONTAINER_END_TRANSLATE_X}, ${CONTAINER_END_TRANSLATE_Y}, 0)` },
-    ];
-    const BACKWARD_CONTAINER_KEYFRAMES = [
-        { offset: 0, transform: `translate3d(${CONTAINER_END_TRANSLATE_X}, ${CONTAINER_END_TRANSLATE_Y}, 0)` },
-        { offset: 1, transform: `translate3d(${CONTAINER_START_TRANSLATE_X}, ${CONTAINER_START_TRANSLATE_Y}, 0)` },
-    ];
-    const CONTAINER_KEYFRAMES = backDirection ? BACKWARD_CONTAINER_KEYFRAMES : FORWARD_CONTAINER_KEYFRAMES;
-    const FORWARD_TEXT_KEYFRAMES = [
-        { offset: 0, opacity: 0, transform: TEXT_START_SCALE },
-        { offset: 1, opacity: 1, transform: TEXT_END_SCALE },
-    ];
-    const BACKWARD_TEXT_KEYFRAMES = [
-        { offset: 0, opacity: 1, transform: TEXT_END_SCALE },
-        { offset: 1, opacity: 0, transform: TEXT_START_SCALE },
-    ];
-    const TEXT_KEYFRAMES = backDirection ? BACKWARD_TEXT_KEYFRAMES : FORWARD_TEXT_KEYFRAMES;
-    const FORWARD_ICON_KEYFRAMES = [
-        { offset: 0, opacity: 0, transform: 'scale(0.6)' },
-        { offset: 0.6, opacity: 0, transform: 'scale(0.6)' },
-        { offset: 1, opacity: 1, transform: 'scale(1)' },
-    ];
-    const BACKWARD_ICON_KEYFRAMES = [
-        { offset: 0, opacity: 1, transform: 'scale(1)' },
-        { offset: 0.2, opacity: 0, transform: 'scale(0.6)' },
-        { offset: 1, opacity: 0, transform: 'scale(0.6)' },
-    ];
-    const ICON_KEYFRAMES = backDirection ? BACKWARD_ICON_KEYFRAMES : FORWARD_ICON_KEYFRAMES;
-    const enteringBackButtonTextAnimation = createAnimation();
-    const enteringBackButtonIconAnimation = createAnimation();
-    const enteringBackButtonAnimation = createAnimation();
-    const clonedBackButtonEl = getClonedElement('ion-back-button');
-    const clonedBackButtonTextEl = shadow(clonedBackButtonEl).querySelector('.button-text');
-    const clonedBackButtonIconEl = shadow(clonedBackButtonEl).querySelector('ion-icon');
-    clonedBackButtonEl.text = backButtonEl.text;
-    clonedBackButtonEl.mode = backButtonEl.mode;
-    clonedBackButtonEl.icon = backButtonEl.icon;
-    clonedBackButtonEl.color = backButtonEl.color;
-    clonedBackButtonEl.disabled = backButtonEl.disabled;
-    clonedBackButtonEl.style.setProperty('display', 'block');
-    clonedBackButtonEl.style.setProperty('position', 'fixed');
-    enteringBackButtonIconAnimation.addElement(clonedBackButtonIconEl);
-    enteringBackButtonTextAnimation.addElement(clonedBackButtonTextEl);
-    enteringBackButtonAnimation.addElement(clonedBackButtonEl);
-    enteringBackButtonAnimation
-        .beforeStyles({
-        position: 'absolute',
-        top: '0px',
-        [CONTAINER_ORIGIN_X]: '0px',
-    })
-        .beforeAddWrite(() => {
-        backButtonEl.style.setProperty('display', 'none');
-        clonedBackButtonEl.style.setProperty(TEXT_ORIGIN_X, BACK_BUTTON_START_OFFSET);
-    })
-        .afterAddWrite(() => {
-        backButtonEl.style.setProperty('display', '');
-        clonedBackButtonEl.style.setProperty('display', 'none');
-        clonedBackButtonEl.style.removeProperty(TEXT_ORIGIN_X);
-    })
-        .keyframes(CONTAINER_KEYFRAMES);
-    enteringBackButtonTextAnimation
-        .beforeStyles({
-        'transform-origin': `${TEXT_ORIGIN_X} top`,
-    })
-        .keyframes(TEXT_KEYFRAMES);
-    enteringBackButtonIconAnimation
-        .beforeStyles({
-        'transform-origin': `${ICON_ORIGIN_X} center`,
-    })
-        .keyframes(ICON_KEYFRAMES);
-    rootAnimation.addAnimation([enteringBackButtonTextAnimation, enteringBackButtonIconAnimation, enteringBackButtonAnimation]);
-};
-const animateLargeTitle = (rootAnimation, rtl, backDirection, largeTitleEl, largeTitleBox, largeTitleTextBox, backButtonBox, backButtonTextEl, backButtonTextBox) => {
-    const ORIGIN_X = rtl ? 'right' : 'left';
-    const TITLE_START_OFFSET = rtl ? `calc(100% - ${largeTitleBox.right}px)` : `${largeTitleBox.left}px`;
-    const START_TRANSLATE_X = '0px';
-    const START_TRANSLATE_Y = `${largeTitleBox.top}px`;
-    const LARGE_TITLE_TRANSLATION_OFFSET = 8;
-    let END_TRANSLATE_X = rtl
-        ? `-${window.innerWidth - backButtonBox.right - LARGE_TITLE_TRANSLATION_OFFSET}px`
-        : `${backButtonBox.x + LARGE_TITLE_TRANSLATION_OFFSET}px`;
-    let HEIGHT_SCALE = 0.5;
-    const START_SCALE = 'scale(1)';
-    let END_SCALE = `scale(${HEIGHT_SCALE})`;
-    if (backButtonTextEl && backButtonTextBox) {
-        END_TRANSLATE_X = rtl
-            ? `-${window.innerWidth - backButtonTextBox.right - LARGE_TITLE_TRANSLATION_OFFSET}px`
-            : `${backButtonTextBox.x - LARGE_TITLE_TRANSLATION_OFFSET}px`;
-        const doTitleAndButtonTextsMatch = backButtonTextEl.textContent?.trim() === largeTitleEl.textContent?.trim();
-        const WIDTH_SCALE = backButtonTextBox.width / largeTitleTextBox.width;
-        HEIGHT_SCALE = backButtonTextBox.height / (largeTitleTextBox.height - LARGE_TITLE_SIZE_OFFSET);
-        END_SCALE = doTitleAndButtonTextsMatch ? `scale(${WIDTH_SCALE}, ${HEIGHT_SCALE})` : `scale(${HEIGHT_SCALE})`;
-    }
-    const backButtonMidPoint = backButtonBox.top + backButtonBox.height / 2;
-    const titleMidPoint = (largeTitleBox.height * HEIGHT_SCALE) / 2;
-    const END_TRANSLATE_Y = `${backButtonMidPoint - titleMidPoint}px`;
-    const BACKWARDS_KEYFRAMES = [
-        { offset: 0, opacity: 0, transform: `translate3d(${END_TRANSLATE_X}, ${END_TRANSLATE_Y}, 0) ${END_SCALE}` },
-        { offset: 0.1, opacity: 0 },
-        { offset: 1, opacity: 1, transform: `translate3d(${START_TRANSLATE_X}, ${START_TRANSLATE_Y}, 0) ${START_SCALE}` },
-    ];
-    const FORWARDS_KEYFRAMES = [
-        {
-            offset: 0,
-            opacity: 0.99,
-            transform: `translate3d(${START_TRANSLATE_X}, ${START_TRANSLATE_Y}, 0) ${START_SCALE}`,
-        },
-        { offset: 0.6, opacity: 0 },
-        { offset: 1, opacity: 0, transform: `translate3d(${END_TRANSLATE_X}, ${END_TRANSLATE_Y}, 0) ${END_SCALE}` },
-    ];
-    const KEYFRAMES = backDirection ? BACKWARDS_KEYFRAMES : FORWARDS_KEYFRAMES;
-    const clonedTitleEl = getClonedElement('ion-title');
-    const clonedLargeTitleAnimation = createAnimation();
-    clonedTitleEl.innerText = largeTitleEl.innerText;
-    clonedTitleEl.size = largeTitleEl.size;
-    clonedTitleEl.color = largeTitleEl.color;
-    clonedLargeTitleAnimation.addElement(clonedTitleEl);
-    clonedLargeTitleAnimation
-        .beforeStyles({
-        'transform-origin': `${ORIGIN_X} top`,
-        height: `${largeTitleBox.height}px`,
-        display: '',
-        position: 'relative',
-        [ORIGIN_X]: TITLE_START_OFFSET,
-    })
-        .beforeAddWrite(() => {
-        largeTitleEl.style.setProperty('opacity', '0');
-    })
-        .afterAddWrite(() => {
-        largeTitleEl.style.setProperty('opacity', '');
-        clonedTitleEl.style.setProperty('display', 'none');
-    })
-        .keyframes(KEYFRAMES);
-    rootAnimation.addAnimation(clonedLargeTitleAnimation);
-};
 export const iosTransitionAnimation = (navEl, opts) => {
     try {
         const EASING = 'cubic-bezier(0.32,0.72,0,1)';
@@ -609,4 +387,3 @@ export const iosTransitionAnimation = (navEl, opts) => {
         throw err;
     }
 };
-const LARGE_TITLE_SIZE_OFFSET = 10;

package/docs/experimental-animation.md

@@ -1,10 +1,10 @@
 ---
-title: Experimental animation
+title: Animation
 ---
 
-# Experimental animation
+# Animation
 
-These gesture and animation helpers are experimental and optional. The theme works without them.
+These gesture and animation helpers are production-ready and optional. The theme works without them.
 
 ## Sheet of Glass with `ion-tab-button` / `ion-segment-button`
 

package/docs/features.md

@@ -11,6 +11,8 @@ Customize the theme with CSS variables and Sass mixins, or adopt it one componen
 To customize the library's default styles to match your design, several CSS variables are provided. See this file for details:
 [Default variables](../src/styles/default-variables.scss)
 
+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`.
+
 ## Liquid Glass mixin
 
 Import the SCSS files from the main package to use the liquid glass mixin.
@@ -23,9 +25,9 @@ ion-textarea label.textarea-wrapper {
 }
 ```
 
-## Native UI Shell
+## Native UI Shell (Experimental)
 
-Capacitor iOS apps can use the optional [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](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.
 
 ## Selective component imports
 
@@ -51,6 +53,7 @@ Always:
 :root {
   @include theme-dark.default-variables;
 }
+@include theme-dark.ion-list;
 @include theme-dark.ion-button;
 @include theme-dark.ion-fab;
 @include theme-dark.ion-tabs;
@@ -66,6 +69,7 @@ System:
   :root {
     @include theme-dark.default-variables;
   }
+  @include theme-dark.ion-list;
   @include theme-dark.ion-button;
   @include theme-dark.ion-fab;
   @include theme-dark.ion-tabs;
@@ -80,6 +84,7 @@ Class:
 
 .ion-palette-dark {
   @include theme-dark.default-variables;
+  @include theme-dark.ion-list;
   @include theme-dark.ion-button;
   @include theme-dark.ion-fab;
   @include theme-dark.ion-tabs;

package/docs/native-ui-shell.md

@@ -1,8 +1,10 @@
 ---
-title: Native UI Shell
+title: Native UI Shell (Experimental)
 ---
 
-# Native UI Shell
+# Native UI Shell (Experimental)
+
+Native UI Shell is experimental. Its API and supported controls may change.
 
 Native UI Shell gives an Ionic app native navigation and action controls around its Web content. The optional Capacitor iOS plugin renders supported fixed Ionic controls with UIKit and the system's Liquid Glass material. Page content, scrolling, application state and routing remain in Ionic's WebView.
 
@@ -54,7 +56,7 @@ If a child inside a shared native surface opts out, the entire surface stays on
 
 Placement is required even when the appearance is glass. Buttons, back buttons, menu-button groups and segments need a toolbar directly inside `ion-header` or `ion-footer`, with no `ion-content` ancestor around the control. Buttons directly inside a header/footer, standalone toolbars, and toolbars or headers nested in scrolling content stay on the Web. FABs without `slot="fixed"` also stay on the Web. Moving a projected control to an excluded location restores its Web rendering; moving it back re-evaluates eligibility.
 
-Native tabs accept equal-width items with Ionic's default `layout="icon-top"`. UIKit adapts the internal icon/label arrangement to the device and size class; on iPad, for example, they can appear side by side. Other explicit Ionic layouts (`icon-start`, `icon-end`, `icon-bottom`, `icon-hide`, `label-hide`) and unequal item widths keep the entire tab bar on the Web. Start, center and end placement follow the original `ion-tab-bar`, including RTL. Directional `ion-icon` artwork preserves its rendered RTL flip.
+Native tabs accept equal-width items with Ionic's default `layout="icon-top"`. The native bar uses a local compact horizontal and regular vertical size class to preserve the Web's stacked icon/label arrangement on iPad and in landscape. This does not change the app's size class. Label size and weight follow the Web snapshot. Other explicit Ionic layouts (`icon-start`, `icon-end`, `icon-bottom`, `icon-hide`, `label-hide`) and unequal item widths keep the entire tab bar on the Web. Start, center and end placement follow the original `ion-tab-bar`, including RTL. Directional `ion-icon` artwork preserves its rendered RTL flip.
 
 Standalone clear, solid and outline buttons are excluded. A glass `ion-buttons` group of two or more clear buttons is projected as one surface; its children retain separate actions. Menu buttons can also share that group. A single menu button uses its parent `ion-buttons` as the glass surface, so no Web glass is left underneath the native button. A menu button outside this theme glass remains on the Web. Mixed fills, unsupported children, or a theme-disabled child keep the group on the Web. Single clear buttons remain on the Web. Custom button colors, custom back icons/colors, collapsing headers, toolbars inside scrolling content, modal content, scrollable/expanded segments and segment-view integration remain on the Web. Complex slots and unsupported SVG features also fall back to Web. The plugin does not translate arbitrary application CSS into UIKit styles.
 
@@ -62,13 +64,13 @@ Native glass samples the Web content actually drawn behind it. Existing toolbar
 
 While a Web input owns the software keyboard, ordinary controls return to Web rendering and are re-evaluated when it closes. This also covers iPad layouts where the keyboard does not move the visual viewport. A native search field keeps its own native keyboard and search surface.
 
-When an existing control becomes unsupported, its Web source is painted before its native cover is removed. This avoids a blank handoff, but Web/UIKit updates are not atomic: dynamically changing an iPad tab bar from a supported to an unsupported width showed 1–2 overlapping frames in a 30 fps recording. This boundary behavior differs from ordinary page navigation, where unchanged shared native tabs are retained.
+When an existing control becomes unsupported, its Web source is painted before its native cover is removed. This avoids a blank handoff, but Web/UIKit updates are not atomic and can briefly overlap. This boundary behavior differs from ordinary page navigation, where unchanged shared native tabs are retained.
 
 ## State and events
 
 Menu buttons use Ionic's resolved default/configured icon or a supported slot icon/label. Native activation clicks the original `ion-menu-button`, preserving `menu` targeting. Non-default menu button types (`submit` / `reset`) remain on the Web. `disabled`, `autoHide`, menu availability and split-pane visibility follow the actual DOM. Opening a menu restores Web controls and retires their native covers; closing it reprojects eligible controls.
 
-The DOM owns labels, SVG content, placement, selected values and application behavior. The placement reference is `ion-tab-bar` itself. The native tab content is sized and aligned to that rectangle, accounting for UITabBar's larger outer frame: `tab-bar-position-start`, `tab-bar-position-center`, and `tab-bar-position-end` control the horizontal anchor (including RTL), while `slot="bottom"` retains the bottom edge and `slot="top"` retains the top edge. Class changes are reconciled automatically. Native item layout and internal margins remain UIKit-owned. UIKit can cap the content width even with fill positioning. If the measured native width cannot match the source within 1 CSS pixel, that tab bar stays on the Web while other supported controls remain native. The plugin does not stretch icons or modify UIKit's internal controls to force CSS item widths. The plugin measures the view subtree containing the native tab controls without private class names or fixed inset corrections; an unrecognized layout restores Web rendering. The runtime watches structural changes, affected shadow roots, sizing, page lifecycle events and overlays. Ancestor `display: none`, `hidden`, theme classes, component removal and disabled changes are reconciled automatically. Native touch events are checked against the current DOM and revision before clicking the original Ionic element.
+The DOM owns labels, SVG content, placement, selected values and application behavior. The placement reference is `ion-tab-bar` itself. The native tab content uses that rectangle as its sizing proposal and placement anchor, accounting for UITabBar's larger outer frame: `tab-bar-position-start`, `tab-bar-position-center`, and `tab-bar-position-end` control the horizontal anchor (including RTL), while `slot="bottom"` retains the bottom edge and `slot="top"` retains the top edge. Class changes are reconciled automatically. UIKit owns internal margins and platter sizing, while the supported stacked layout and label typography follow the Web. UIKit can cap the content width even with fill positioning. On viewports at least 768px wide, the Web theme caps standard two-, three-, four- and five-item bars near the iPad stacked platter measurements (188, 274, 336 and 414pt). Smaller viewports retain the phone sizing. The standard bar is 62pt high, with a 54pt selection and a 4pt inset. Adjacent buttons overlap like UIKit’s controls; icon and label alignment is checked against simulator screenshots. These are default appearance targets, not a guarantee for custom fonts, icons or labels; UIKit still determines its intrinsic width. A different native width or height does not reject projection. Badge and title updates retain native item identities and remeasure the platter at the same placement anchor. The plugin does not stretch icons or modify UIKit's internal controls to force CSS item widths. The plugin measures the view subtree containing the native tab controls without private class names or fixed inset corrections; an unrecognized layout restores Web rendering. The runtime watches structural changes, affected shadow roots, sizing, page lifecycle events and overlays. Ancestor `display: none`, `hidden`, theme classes, component removal and disabled changes are reconciled automatically. Native touch events are checked against the current DOM and revision before clicking the original Ionic element.
 
 For forms, retain `ion-button type="submit"` and the form's existing submit handler. An external form is still passed as `[form]="formRef"`. The plugin does not call `form.submit()`, add a second submit path or change Angular form ownership. Segment values retain their original type because the original `ion-segment-button` is clicked; programmatic value changes do not emit a synthetic `ionChange`.
 
@@ -132,3 +134,5 @@ On iOS, [`Components`](../ios/Sources/IonicNativeUIShellPlugin/Components) owns
 
 See the [demo and verification guide](../demo/native-ui-shell.md) for browser tests, Simulator tests and an independent SPM consumer built from the npm package.
 
+
+Search controllers retain their UIKit-managed transition and are excluded from the ordinary control acquisition crossfade.

package/docs/special-markup.md

@@ -17,6 +17,23 @@ Solid submit buttons use the Ionic color's contrast value for their foreground.
 
 Use `.button-submit` when the button needs the same treatment but cannot use `type="submit"`.
 
+## Preferred overlay actions
+
+For iOS alerts and action sheets, set `role: 'preferred'` on a button to give it a filled `--ion-color-primary` background and `--ion-color-primary-contrast` text and icons. While pressed, the background uses `--ion-color-primary-shade`. This is a theme convention using Ionic's custom button roles; it does not automatically select or invoke the action. Dismissal reports the role as `preferred`.
+
+```ts
+buttons: [
+  { text: 'Cancel', role: 'cancel' },
+  { text: 'Continue', role: 'preferred' },
+];
+```
+
+Buttons with no role or `default` keep the normal text color. `cancel` retains Ionic's cancellation behavior, `selected` remains a selection state, and `destructive` uses `--ios-theme-destructive-color`. An existing `confirm` role is not treated as preferred. Use `preferred` for the recommended action, not simply any action that confirms a choice.
+
+## Floating iPad sheets
+
+Set `expandToScroll: false` on a sheet modal to use floating lower corners and a 20px bottom gap on iPad. Ionic then sizes the visible page at each breakpoint, so the theme can style it with CSS alone. Content scrolls within the current breakpoint; dragging the handle still resizes the sheet. With the default `expandToScroll: true`, the sheet keeps Ionic's bottom-attached layout and scroll-to-expand behavior.
+
 ## Tab bar position
 
 Add one of `tab-bar-position-start`, `tab-bar-position-center`, or `tab-bar-position-end` to an iOS `ion-tab-bar` to position the whole bar within its safe area. These classes work with both `slot="top"` and `slot="bottom"` and preserve the bar's width and press animation. Start and end follow the text direction (reversed in RTL). Without a class, the existing placement is unchanged.

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellButton.swift

@@ -18,8 +18,9 @@ enum ShellButton {
         var configuration: UIButton.Configuration = glass ? .glass() : .plain()
         configuration.title = item.label
         configuration.image = rendering.image(item)
-        configuration.imagePadding = 4
-        configuration.contentInsets = NSDirectionalEdgeInsets(top: 0, leading: 4, bottom: 0, trailing: 4)
+        configuration.imagePadding = item.imagePadding ?? 4
+        configuration.contentInsets = NSDirectionalEdgeInsets(top: 0, leading: item.contentInsetLeading ?? 4,
+                                                            bottom: 0, trailing: item.contentInsetTrailing ?? 4)
         configuration.imagePlacement = item.iconPosition == .trailing ? .trailing : .leading
         configuration.baseForegroundColor = rendering.color(item.color)
         configuration.titleLineBreakMode = .byTruncatingTail
@@ -33,6 +34,10 @@ enum ShellButton {
         let button = existing ?? UIButton(configuration: configuration)
         if existing != nil { button.configuration = configuration }
         button.titleLabel?.numberOfLines = 1
+        // Web and UIKit can differ by a fraction of a point in text measurement.
+        // Absorb that rounding without widening the projected button.
+        button.titleLabel?.adjustsFontSizeToFitWidth = true
+        button.titleLabel?.minimumScaleFactor = 0.99
         button.isEnabled = !item.disabled
         button.accessibilityLabel = item.accessibilityLabel
         button.accessibilityIdentifier = item.id

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellSearchController.swift

@@ -58,6 +58,7 @@ final class ShellSearchController: UITabBarController, UITabBarControllerDelegat
     private var editingSequence = 0
     private var valueVersion = -1
     private var lastLayout = ""
+    private var layoutItems: [ShellItemContent] = []
     var ownsKeyboard: Bool { search.searchBar.searchTextField.isFirstResponder }
     var activate: ((String) -> Void)?
     var changed: ((String, ShellSearchPhase, String, Bool, Int) -> Int)?
@@ -70,6 +71,7 @@ final class ShellSearchController: UITabBarController, UITabBarControllerDelegat
         surface.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         delegate = self
         mode = .tabBar
+        ShellTabBar.configureLayout(tabBar)
         search.obscuresBackgroundDuringPresentation = false
         search.hidesNavigationBarDuringPresentation = false
         search.searchBar.delegate = self
@@ -122,6 +124,13 @@ final class ShellSearchController: UITabBarController, UITabBarControllerDelegat
         // advance native editing beyond the last input accepted by Ionic.
         if !active { closing = true }
         let items = snapshot.items
+        let content = items.map(\.content)
+        if layoutItems != content {
+            layoutItems = content
+            // Defer fitting while search is active, but keep the resting layout
+            // invalid until new labels, typography, icons and badges are measured.
+            lastLayout = ""
+        }
         let ids = items.map(\.id)
         for id in Array(ordinary.keys) where !ids.contains(id) { ordinary.removeValue(forKey: id) }
         for item in items {
@@ -148,6 +157,7 @@ final class ShellSearchController: UITabBarController, UITabBarControllerDelegat
         for item in items {
             if let nativeItem = ordinary[item.id]?.viewController?.tabBarItem {
                 nativeItem.accessibilityLabel = item.content.accessibilityLabel
+                ShellTabBar.applyTypography(item.content, to: nativeItem)
                 ShellTabBar.applyBadge(item.content.badge, to: nativeItem, rendering: rendering)
             }
         }

package/ios/Sources/IonicNativeUIShellPlugin/Components/ShellSegment.swift

@@ -8,6 +8,7 @@ private final class ShellSegmentElement: UIAccessibilityElement {
 final class ShellSegment: UISegmentedControl {
     static let kind = ShellComponent.segment
     var labels: [String] = []
+    private var items: [ShellItem] = []
     override func layoutSubviews() {
         super.layoutSubviews()
         let total = (0..<numberOfSegments).reduce(CGFloat.zero) { $0 + widthForSegment(at: $1) }
@@ -35,25 +36,56 @@ final class ShellSegment: UISegmentedControl {
 
     @available(iOS 26.0, *)
     static func make(_ node: ShellControl, scale: CGFloat, rendering: ShellRendering, activate: @escaping (String) -> Void) -> UISegmentedControl? {
-        let items = node.items
-        guard let firstItem = items.first else { return nil }
-        let rtl = node.rtl
-        let control = ShellSegment(items: items.map { rendering.image($0.content) as Any? ?? $0.content.label })
-        control.labels = items.map { $0.content.accessibilityLabel }
+        guard !node.items.isEmpty else { return nil }
+        let control = ShellSegment(items: [])
         control.isAccessibilityElement = false
-        control.setTitleTextAttributes([.font: UIFont.systemFont(ofSize: firstItem.content.fontSize, weight: .medium)], for: .normal)
-        control.semanticContentAttribute = rtl ? .forceRightToLeft : .forceLeftToRight
         control.apportionsSegmentWidthsByContent = false
-        for (index, item) in items.enumerated() {
-            control.setEnabled(!item.content.disabled, forSegmentAt: index)
-            control.setWidth(item.frame.width * scale, forSegmentAt: index)
-            if item.content.selected { control.selectedSegmentIndex = index }
-        }
-        control.accessibilityIdentifier = node.id
+        control.update(node, scale: scale, rendering: rendering)
         control.addAction(UIAction { [weak control] _ in
-            guard let control, items.indices.contains(control.selectedSegmentIndex) else { return }
-            activate(items[control.selectedSegmentIndex].id)
+            guard let control, control.items.indices.contains(control.selectedSegmentIndex) else { return }
+            activate(control.items[control.selectedSegmentIndex].id)
         }, for: .valueChanged)
         return control
     }
+
+    @available(iOS 26.0, *)
+    func update(_ node: ShellControl, scale: CGFloat, rendering: ShellRendering) {
+        let previous = items
+        let rebuilt = previous.map(\.id) != node.items.map(\.id)
+        if rebuilt {
+            removeAllSegments()
+            for index in node.items.indices { insertSegment(withTitle: "", at: index, animated: false) }
+        }
+        if let first = node.items.first, previous.first?.content.fontSize != first.content.fontSize {
+            setTitleTextAttributes([.font: UIFont.systemFont(ofSize: first.content.fontSize, weight: .medium)], for: .normal)
+        }
+        let direction: UISemanticContentAttribute = node.rtl ? .forceRightToLeft : .forceLeftToRight
+        if semanticContentAttribute != direction { semanticContentAttribute = direction }
+        // Ionic button frames exclude their margins. Distribute the full track
+        // width so UIKit's fixed segment widths do not shrink the projected track.
+        let totalItemWidth = node.items.reduce(0.0) { $0 + $1.frame.width }
+        let widthScale = totalItemWidth > 0 ? node.frame.width / totalItemWidth * scale : scale
+        for (index, item) in node.items.enumerated() {
+            let old = rebuilt ? nil : previous[index].content
+            let content = item.content
+            if old?.label != content.label || old?.icon != content.icon ||
+                old?.iconWidth != content.iconWidth || old?.iconHeight != content.iconHeight ||
+                old?.iconTemplate != content.iconTemplate || old?.color != content.color {
+                let image = rendering.image(content)
+                setImage(image, forSegmentAt: index)
+                setTitle(image == nil ? content.label : nil, forSegmentAt: index)
+            }
+            if isEnabledForSegment(at: index) == content.disabled { setEnabled(!content.disabled, forSegmentAt: index) }
+            let width = item.frame.width * widthScale
+            if widthForSegment(at: index) != width { setWidth(width, forSegmentAt: index) }
+        }
+        items = node.items
+        labels = items.map { $0.content.accessibilityLabel }
+        accessibilityIdentifier = node.id
+        let selected = items.firstIndex { $0.content.selected } ?? UISegmentedControl.noSegment
+        // A native tap has already selected this index. Reassigning it can interrupt
+        // UIKit's in-flight lens animation when the Web selection echoes back.
+        if selectedSegmentIndex != selected { selectedSegmentIndex = selected }
+        setNeedsLayout()
+    }
 }