voyager-ionic-core 8.7.2 → 8.7.9

package/dist/collection/utils/overlays.js

@@ -11,7 +11,6 @@ import { CoreDelegate } from "./framework-delegate";
 import { BACKDROP_NO_SCROLL } from "./gesture/gesture-controller";
 import { OVERLAY_BACK_BUTTON_PRIORITY } from "./hardware-back-button";
 import { addEventListener, componentOnReady, focusVisibleElement, getElementRoot, removeEventListener, } from "./helpers";
-import { isPlatform } from "./platform";
 let lastOverlayIndex = 0;
 let lastId = 0;
 export const activeAnimations = new WeakMap();
@@ -412,7 +411,7 @@ export const getPresentedOverlay = (doc, overlayTag, id) => {
  */
 export const setRootAriaHidden = (hidden = false) => {
     const root = getAppRoot(document);
-    const viewContainer = root.querySelector('ion-router-outlet, ion-nav, #ion-view-container-root');
+    const viewContainer = root.querySelector('ion-router-outlet, #ion-view-container-root');
     if (!viewContainer) {
         return;
     }
@@ -428,21 +427,50 @@ export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation
     if (overlay.presented) {
         return;
     }
+    /**
+     * When an overlay that steals focus
+     * is dismissed, focus should be returned
+     * to the element that was focused
+     * prior to the overlay opening. Toast
+     * does not steal focus and is excluded
+     * from returning focus as a result.
+     */
+    if (overlay.el.tagName !== 'ION-TOAST') {
+        restoreElementFocus(overlay.el);
+    }
     /**
      * Due to accessibility guidelines, toasts do not have
      * focus traps.
      *
      * All other overlays should have focus traps to prevent
-     * the keyboard focus from leaving the overlay.
+     * the keyboard focus from leaving the overlay unless
+     * developers explicitly opt out (for example, sheet
+     * modals that should permit background interaction).
+     *
+     * Note: Some apps move inline overlays to a specific container
+     * during the willPresent lifecycle (e.g., React portals via
+     * onWillPresent). Defer applying aria-hidden/inert to the app
+     * root until after willPresent so we can detect where the
+     * overlay is finally inserted. If the overlay is inside the
+     * view container subtree, skip adding aria-hidden/inert there
+     * to avoid disabling the overlay.
      */
-    if (overlay.el.tagName !== 'ION-TOAST') {
-        setRootAriaHidden(true);
-        document.body.classList.add(BACKDROP_NO_SCROLL);
-    }
-    hideUnderlyingOverlaysFromScreenReaders(overlay.el);
-    hideAnimatingOverlayFromScreenReaders(overlay.el);
+    const overlayEl = overlay.el;
+    const shouldTrapFocus = overlayEl.tagName !== 'ION-TOAST' && overlayEl.focusTrap !== false;
+    // Only lock out root content when backdrop is active. Developers relying on showBackdrop=false
+    // expect background interaction to remain enabled.
+    const shouldLockRoot = shouldTrapFocus && overlayEl.showBackdrop !== false;
     overlay.presented = true;
     overlay.willPresent.emit();
+    if (shouldLockRoot) {
+        const root = getAppRoot(document);
+        const viewContainer = root.querySelector('ion-router-outlet, #ion-view-container-root');
+        const overlayInsideViewContainer = viewContainer ? viewContainer.contains(overlayEl) : false;
+        if (!overlayInsideViewContainer) {
+            setRootAriaHidden(true);
+        }
+        document.body.classList.add(BACKDROP_NO_SCROLL);
+    }
     (_a = overlay.willPresentShorthand) === null || _a === void 0 ? void 0 : _a.emit();
     const mode = getIonMode(overlay);
     // get the user's animation fn if one was provided
@@ -454,17 +482,6 @@ export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation
         overlay.didPresent.emit();
         (_b = overlay.didPresentShorthand) === null || _b === void 0 ? void 0 : _b.emit();
     }
-    /**
-     * When an overlay that steals focus
-     * is dismissed, focus should be returned
-     * to the element that was focused
-     * prior to the overlay opening. Toast
-     * does not steal focus and is excluded
-     * from returning focus as a result.
-     */
-    if (overlay.el.tagName !== 'ION-TOAST') {
-        restoreElementFocus(overlay.el);
-    }
     /**
      * If the focused element is already
      * inside the overlay component then
@@ -487,6 +504,7 @@ export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation
      * screen readers.
      */
     overlay.el.removeAttribute('aria-hidden');
+    overlay.el.removeAttribute('inert');
 };
 /**
  * When an overlay component is dismissed,
@@ -503,6 +521,8 @@ const restoreElementFocus = async (overlayEl) => {
     if (!previousElement) {
         return;
     }
+    // Ensure active element is blurred to prevent a11y warning issues
+    previousElement.blur();
     const shadowRoot = previousElement === null || previousElement === void 0 ? void 0 : previousElement.shadowRoot;
     if (shadowRoot) {
         // If there are no inner focusable elements, just focus the host element.
@@ -547,31 +567,29 @@ export const dismiss = async (overlay, data, role, name, iosLeaveAnimation, mdLe
      * For accessibility, toasts lack focus traps and don't receive
      * `aria-hidden` on the root element when presented.
      *
-     * All other overlays use focus traps to keep keyboard focus
-     * within the overlay, setting `aria-hidden` on the root element
-     * to enhance accessibility.
-     *
-     * Therefore, we must remove `aria-hidden` from the root element
-     * when the last non-toast overlay is dismissed.
+     * Overlays that opt into focus trapping set `aria-hidden`
+     * on the root element to keep keyboard focus and pointer
+     * events inside the overlay. We must remove `aria-hidden`
+     * from the root element when the last focus-trapping overlay
+     * is dismissed.
      */
-    const overlaysNotToast = presentedOverlays.filter((o) => o.tagName !== 'ION-TOAST');
-    const lastOverlayNotToast = overlaysNotToast.length === 1 && overlaysNotToast[0].id === overlay.el.id;
+    const overlaysLockingRoot = presentedOverlays.filter((o) => {
+        const el = o;
+        return el.tagName !== 'ION-TOAST' && el.focusTrap !== false && el.showBackdrop !== false;
+    });
+    const overlayEl = overlay.el;
+    const locksRoot = overlayEl.tagName !== 'ION-TOAST' && overlayEl.focusTrap !== false && overlayEl.showBackdrop !== false;
     /**
-     * If this is the last visible overlay that is not a toast
+     * If this is the last visible overlay that is trapping focus
      * then we want to re-add the root to the accessibility tree.
      */
-    if (lastOverlayNotToast) {
+    const lastOverlayTrappingFocus = locksRoot && overlaysLockingRoot.length === 1 && overlaysLockingRoot[0].id === overlayEl.id;
+    if (lastOverlayTrappingFocus) {
         setRootAriaHidden(false);
         document.body.classList.remove(BACKDROP_NO_SCROLL);
     }
     overlay.presented = false;
     try {
-        /**
-         * There is no need to show the overlay to screen readers during
-         * the dismiss animation. This is because the overlay will be removed
-         * from the DOM after the animation is complete.
-         */
-        hideAnimatingOverlayFromScreenReaders(overlay.el);
         // Overlay contents should not be clickable during dismiss
         overlay.el.style.setProperty('pointer-events', 'none');
         overlay.willDismiss.emit({ data, role });
@@ -610,7 +628,6 @@ export const dismiss = async (overlay, data, role, name, iosLeaveAnimation, mdLe
         printIonError(`[${overlay.el.tagName.toLowerCase()}] - `, err);
     }
     overlay.el.remove();
-    revealOverlaysToScreenReaders();
     return true;
 };
 const getAppRoot = (doc) => {
@@ -806,91 +823,4 @@ export const createTriggerController = () => {
         removeClickListener,
     };
 };
-/**
- * The overlay that is being animated also needs to hide from screen
- * readers during its animation. This ensures that assistive technologies
- * like TalkBack do not announce or interact with the content until the
- * animation is complete, avoiding confusion for users.
- *
- * When the overlay is presented on an Android device, TalkBack's focus rings
- * may appear in the wrong position due to the transition (specifically
- * `transform` styles). This occurs because the focus rings are initially
- * displayed at the starting position of the elements before the transition
- * begins. This workaround ensures the focus rings do not appear in the
- * incorrect location.
- *
- * If this solution is applied to iOS devices, then it leads to a bug where
- * the overlays cannot be accessed by screen readers. This is due to
- * VoiceOver not being able to update the accessibility tree when the
- * `aria-hidden` is removed.
- *
- * @param overlay - The overlay that is being animated.
- */
-const hideAnimatingOverlayFromScreenReaders = (overlay) => {
-    if (doc === undefined)
-        return;
-    if (isPlatform('android')) {
-        /**
-         * Once the animation is complete, this attribute will be removed.
-         * This is done at the end of the `present` method.
-         */
-        overlay.setAttribute('aria-hidden', 'true');
-    }
-};
-/**
- * Ensure that underlying overlays have aria-hidden if necessary so that screen readers
- * cannot move focus to these elements. Note that we cannot rely on focus/focusin/focusout
- * events here because those events do not fire when the screen readers moves to a non-focusable
- * element such as text.
- * Without this logic screen readers would be able to move focus outside of the top focus-trapped overlay.
- *
- * @param newTopMostOverlay - The overlay that is being presented. Since the overlay has not been
- * fully presented yet at the time this function is called it will not be included in the getPresentedOverlays result.
- */
-const hideUnderlyingOverlaysFromScreenReaders = (newTopMostOverlay) => {
-    var _a;
-    if (doc === undefined)
-        return;
-    const overlays = getPresentedOverlays(doc);
-    for (let i = overlays.length - 1; i >= 0; i--) {
-        const presentedOverlay = overlays[i];
-        const nextPresentedOverlay = (_a = overlays[i + 1]) !== null && _a !== void 0 ? _a : newTopMostOverlay;
-        /**
-         * If next overlay has aria-hidden then all remaining overlays will have it too.
-         * Or, if the next overlay is a Toast that does not have aria-hidden then current overlay
-         * should not have aria-hidden either so focus can remain in the current overlay.
-         */
-        if (nextPresentedOverlay.hasAttribute('aria-hidden') || nextPresentedOverlay.tagName !== 'ION-TOAST') {
-            presentedOverlay.setAttribute('aria-hidden', 'true');
-        }
-    }
-};
-/**
- * When dismissing an overlay we need to reveal the new top-most overlay to screen readers.
- * If the top-most overlay is a Toast we potentially need to reveal more overlays since
- * focus is never automatically moved to the Toast.
- */
-const revealOverlaysToScreenReaders = () => {
-    if (doc === undefined)
-        return;
-    const overlays = getPresentedOverlays(doc);
-    for (let i = overlays.length - 1; i >= 0; i--) {
-        const currentOverlay = overlays[i];
-        /**
-         * If the current we are looking at is a Toast then we can remove aria-hidden.
-         * However, we potentially need to keep looking at the overlay stack because there
-         * could be more Toasts underneath. Additionally, we need to unhide the closest non-Toast
-         * overlay too so focus can move there since focus is never automatically moved to the Toast.
-         */
-        currentOverlay.removeAttribute('aria-hidden');
-        /**
-         * If we found a non-Toast element then we can just remove aria-hidden and stop searching entirely
-         * since this overlay should always receive focus. As a result, all underlying overlays should still
-         * be hidden from screen readers.
-         */
-        if (currentOverlay.tagName !== 'ION-TOAST') {
-            break;
-        }
-    }
-};
 export const FOCUS_TRAP_DISABLE_CLASS = 'ion-disable-focus-trap';

package/dist/collection/utils/test/playwright/page/utils/spy-on-event.js

@@ -3,6 +3,38 @@
  */
 import { addE2EListener, EventSpy } from "../event-spy";
 export const spyOnEvent = async (page, eventName) => {
+    /**
+     * Tabbing out of the page boundary can lead to unreliable `ionBlur events,
+     * particularly in Firefox.
+     *
+     * This occurs because Playwright may incorrectly maintain focus state on the
+     * last element, even after a Tab press attempts to shift focus outside the
+     * viewport. To reliably trigger the necessary blur event, add a visually
+     * hidden, focusable element at the end of the page to receive focus instead of
+     * the browser.
+     *
+     * Playwright issue reference:
+     * https://github.com/microsoft/playwright/issues/32269
+     */
+    if (eventName === 'ionBlur') {
+        const hiddenInput = await page.$('#hidden-input-for-ion-blur');
+        if (!hiddenInput) {
+            await page.evaluate(() => {
+                const input = document.createElement('input');
+                input.id = 'hidden-input-for-ion-blur';
+                input.style.position = 'absolute';
+                input.style.opacity = '0';
+                input.style.height = '0';
+                input.style.width = '0';
+                input.style.pointerEvents = 'none';
+                document.body.appendChild(input);
+                // Clean up the element when the page is unloaded.
+                window.addEventListener('unload', () => {
+                    input.remove();
+                });
+            });
+        }
+    }
     const spy = new EventSpy(eventName);
     const handle = await page.evaluateHandle(() => window);
     await addE2EListener(page, handle, eventName, (ev) => spy.push(ev));

package/dist/collection/utils/transition/index.js

@@ -10,11 +10,22 @@ const iosTransitionAnimation = () => import('./ios.transition');
 const mdTransitionAnimation = () => import('./md.transition');
 const focusController = createFocusController();
 // TODO(FW-2832): types
+/**
+ * Executes the main page transition.
+ * It also manages the lifecycle of header visibility (if any)
+ * to prevent visual flickering in iOS. The flickering only
+ * occurs for a condensed header that is placed above the content.
+ *
+ * @param opts Options for the transition.
+ * @returns A promise that resolves when the transition is complete.
+ */
 export const transition = (opts) => {
     return new Promise((resolve, reject) => {
         writeTask(() => {
-            beforeTransition(opts);
-            runTransition(opts).then((result) => {
+            const transitioningInactiveHeader = getIosIonHeader(opts);
+            beforeTransition(opts, transitioningInactiveHeader);
+            runTransition(opts)
+                .then((result) => {
                 if (result.animation) {
                     result.animation.destroy();
                 }
@@ -23,15 +34,21 @@ export const transition = (opts) => {
             }, (error) => {
                 afterTransition(opts);
                 reject(error);
+            })
+                .finally(() => {
+                // Ensure that the header is restored to its original state.
+                setHeaderTransitionClass(transitioningInactiveHeader, false);
             });
         });
     });
 };
-const beforeTransition = (opts) => {
+const beforeTransition = (opts, transitioningInactiveHeader) => {
     const enteringEl = opts.enteringEl;
     const leavingEl = opts.leavingEl;
     focusController.saveViewFocus(leavingEl);
     setZIndex(enteringEl, leavingEl, opts.direction);
+    // Prevent flickering of the header by adding a class.
+    setHeaderTransitionClass(transitioningInactiveHeader, true);
     if (opts.showGoBack) {
         enteringEl.classList.add('can-go-back');
     }
@@ -220,6 +237,39 @@ const setZIndex = (enteringEl, leavingEl, direction) => {
         leavingEl.style.zIndex = '100';
     }
 };
+/**
+ * Add a class to ensure that the header (if any)
+ * does not flicker during the transition. By adding the
+ * transitioning class, we ensure that the header has
+ * the necessary styles to prevent the following flickers:
+ * 1. When entering a page with a condensed header, the
+ * header should never be visible. However,
+ * it briefly renders the background color while
+ * the transition is occurring.
+ * 2. When leaving a page with a condensed header, the
+ * header has an opacity of 0 and the pages
+ * have a z-index which causes the entering page to
+ * briefly show it's content underneath the leaving page.
+ * 3. When entering a page or leaving a page with a fade
+ * header, the header should not have a background color.
+ * However, it briefly shows the background color while
+ * the transition is occurring.
+ *
+ * @param header The header element to modify.
+ * @param isTransitioning Whether the transition is occurring.
+ */
+const setHeaderTransitionClass = (header, isTransitioning) => {
+    if (!header) {
+        return;
+    }
+    const transitionClass = 'header-transitioning';
+    if (isTransitioning) {
+        header.classList.add(transitionClass);
+    }
+    else {
+        header.classList.remove(transitionClass);
+    }
+};
 export const getIonPageElement = (element) => {
     if (element.classList.contains('ion-page')) {
         return element;
@@ -231,3 +281,24 @@ export const getIonPageElement = (element) => {
     // idk, return the original element so at least something animates and we don't have a null pointer
     return element;
 };
+/**
+ * Retrieves the ion-header element from a page based on the
+ * direction of the transition.
+ *
+ * @param opts Options for the transition.
+ * @returns The ion-header element or null if not found or not in 'ios' mode.
+ */
+const getIosIonHeader = (opts) => {
+    const enteringEl = opts.enteringEl;
+    const leavingEl = opts.leavingEl;
+    const direction = opts.direction;
+    const mode = opts.mode;
+    if (mode !== 'ios') {
+        return null;
+    }
+    const element = direction === 'back' ? leavingEl : enteringEl;
+    if (!element) {
+        return null;
+    }
+    return element.querySelector('ion-header');
+};