@ionic/core 9.0.2 → 9.0.3-dev.11788456135.1ab1d6cd

package/dist/collection/utils/menu-controller/animations/reveal.js

@@ -11,9 +11,10 @@ import { baseAnimation } from "./base";
  */
 export const menuRevealAnimation = (menu) => {
     const mode = getIonMode(menu);
+    const isIOS = mode === 'ios';
     const openedX = menu.width * (menu.isEndSide ? -1 : 1) + 'px';
     const contentOpen = createAnimation()
         .addElement(menu.contentEl) // REVIEW
         .fromTo('transform', 'translateX(0px)', `translateX(${openedX})`);
-    return baseAnimation(mode === 'ios').addAnimation(contentOpen);
+    return baseAnimation(isIOS).addAnimation(contentOpen);
 };

package/dist/collection/utils/overlay-control-label.js

@@ -1,11 +1,12 @@
 /*!
  * (C) Ionic http://ionicframework.com - MIT License
  */
-// TODO(FW-6886, FW-6892, FW-6891): Remove this file in favor of the Modular Ionic component config. Each overlay will be able to select its own defaults for label placement and justify based on the interface and mode, so this utility will no longer be necessary.
+// TODO(FW-6886, FW-6892, FW-6891): Remove this file in favor of the Modular Ionic component config. Each overlay will be able to select its own defaults for label placement and justify based on the interface and theme, so this utility will no longer be necessary.
 /**
  * Returns the default `labelPlacement` for a radio or checkbox option
- * rendered inside an overlay. Defaults follow each mode's established
+ * rendered inside an overlay. Defaults follow each theme's established
  * option-row layout:
+ * - `ionic`: always `"start"`.
  * - `ios`: `"start"` for radio in `alert` and `popover`. The `modal`
  *   interface flips iOS radio back to `"end"`. Checkbox is always
  *   `"end"` on iOS.
@@ -14,18 +15,19 @@
  * `interfaceType` is optional; only `"modal"` changes the result, so
  * callers that aren't a modal can omit it.
  *
- * Used by `select-popover` and `select-modal` as the fallback when an
- * option doesn't explicitly set `labelPlacement`.
+ * Used by `alert`, `select-popover`, and `select-modal` as the fallback
+ * when an option doesn't explicitly set `labelPlacement`.
  */
-export const getOverlayLabelPlacement = (mode, control, interfaceType) => {
-    if (mode === 'ios' && control === 'radio' && interfaceType !== 'modal') {
+export const getOverlayLabelPlacement = (theme, control, interfaceType) => {
+    if (theme === 'ionic' || (theme === 'ios' && control === 'radio' && interfaceType !== 'modal')) {
         return 'start';
     }
     return 'end';
 };
 /**
  * Returns the default `justify` for a radio or checkbox option rendered
- * inside an overlay. Defaults follow each mode's option-row layout:
+ * inside an overlay. Defaults follow each theme's option-row layout:
+ * - `ionic`: always `"space-between"`.
  * - `ios`: `"space-between"` for radio in `alert` and `popover`. The
  *   `modal` interface falls back to `"start"`. Checkbox is always `"start"`
  *   on iOS.
@@ -34,11 +36,11 @@ export const getOverlayLabelPlacement = (mode, control, interfaceType) => {
  * `interfaceType` is optional; only `"modal"` changes the result, so
  * callers that aren't a modal can omit it.
  *
- * Used by `select-popover` and `select-modal` as the fallback when an
- * option doesn't explicitly set `justify`.
+ * Used by `alert`, `select-popover`, and `select-modal` as the fallback when
+ * an option doesn't explicitly set `justify`.
  */
-export const getOverlayLabelJustify = (mode, control, interfaceType) => {
-    if (mode === 'ios' && control === 'radio' && interfaceType !== 'modal') {
+export const getOverlayLabelJustify = (theme, control, interfaceType) => {
+    if (theme === 'ionic' || (theme === 'ios' && control === 'radio' && interfaceType !== 'modal')) {
         return 'space-between';
     }
     return 'start';

package/dist/collection/utils/overlays.js

@@ -6,7 +6,7 @@ import { focusFirstDescendant, focusLastDescendant, focusableQueryString } from
 import { shouldUseCloseWatcher } from "./hardware-back-button";
 import { printIonError, printIonWarning } from "./logging/index";
 import { config } from "../global/config";
-import { getIonMode } from "../global/ionic-global";
+import { getIonMode, getIonTheme } from "../global/ionic-global";
 import { CoreDelegate } from "./framework-delegate";
 import { BACKDROP_NO_SCROLL } from "./gesture/gesture-controller";
 import { OVERLAY_BACK_BUTTON_PRIORITY } from "./hardware-back-button";
@@ -14,8 +14,114 @@ import { addEventListener, componentOnReady, focusVisibleElement, getElementRoot
 let lastOverlayIndex = 0;
 let lastId = 0;
 export const activeAnimations = new WeakMap();
+const OVERLAY_FOCUS_TRAP_SELECTOR = 'ion-alert,ion-action-sheet,ion-loading,ion-modal,ion-popover';
 /**
- * Determines if the overlay's backdrop is always blocking (no background interaction).
+ * The focus trap is generic and knows nothing about which components are
+ * inside an overlay. Components mark their elements with these `data-*`
+ * attributes, which the trap reads, to control how Tab moves through them.
+ * This keeps private component class names (e.g. `.modal-handle`,
+ * `.action-sheet-button`) out of the trap, so changing a component does
+ *  not silently break Tab order.
+ *
+ * - `data-focus-ignore`: skip this element as a tab stop.
+ * - `data-focus-order`: explicit numeric placement in the tab sequence.
+ * - `data-roving-focus`: a container whose focusable descendants share a
+ *   single tab stop via a roving tabindex.
+ */
+const FOCUS_IGNORE_SELECTOR = '[data-focus-ignore]';
+const FOCUS_ORDER_SELECTOR = '[data-focus-order]';
+const ROVING_FOCUS_SELECTOR = '[data-roving-focus]';
+/**
+ * Returns the roving-focus group an element belongs to, or `null`.
+ * A member is a descendant of a `[data-roving-focus]` container. The
+ * container itself is not a member. Members share a single tab stop.
+ */
+const getRovingFocusGroup = (el) => {
+    const group = el.closest(ROVING_FOCUS_SELECTOR);
+    return group !== null && group !== el ? group : null;
+};
+/**
+ * Whether an element participates in a roving-focus group.
+ */
+const isRovingFocusItem = (el) => getRovingFocusGroup(el) !== null;
+/**
+ * Returns the currently focused element for keyboard focus checks.
+ *
+ * Starts from `document.activeElement` (non-shadow / light DOM focus).
+ * If focus is inside one or more open shadow roots
+ * (e.g. native control inside `ion-radio`), walks through nested
+ * `shadowRoot.activeElement` values until the innermost focused node is reached.
+ */
+const getActiveElement = (ownerDoc) => {
+    let active = ownerDoc.activeElement;
+    if (!active) {
+        return null;
+    }
+    while (active.shadowRoot?.activeElement) {
+        active = active.shadowRoot.activeElement;
+    }
+    return active;
+};
+/**
+ * Walks from a focused node (possibly deep inside shadow roots) up to
+ * the nearest roving-focus host (e.g. `ion-radio` inside an
+ * `ion-radio-group`, or an action sheet `<button role="radio">`).
+ */
+const getRovingFocusHost = (active) => {
+    let n = active;
+    while (n) {
+        if (isRovingFocusItem(n)) {
+            return n;
+        }
+        const root = n.getRootNode();
+        if (root instanceof ShadowRoot && root.host instanceof HTMLElement) {
+            n = root.host;
+        }
+        else {
+            return null;
+        }
+    }
+    return null;
+};
+/**
+ * Reorders focusables for components that declare an explicit tab order
+ * via `data-focus-order`. Elements without the attribute keep their
+ * visual order and are visited first. Elements with it are appended
+ * afterwards, sorted by ascending numeric value.
+ *
+ * Example (sheet modal): the options have no order and are visited
+ * first in visual order, then the drag handle (`data-focus-order="1"`),
+ * then the header Cancel button (`data-focus-order="2"`).
+ */
+const applyFocusOrder = (elements) => {
+    const sortByVisualPosition = (els) => [...els].sort((a, b) => {
+        const ra = a.getBoundingClientRect();
+        const rb = b.getBoundingClientRect();
+        const topDiff = ra.top - rb.top;
+        if (Math.abs(topDiff) > 1) {
+            return topDiff;
+        }
+        return ra.left - rb.left;
+    });
+    const unordered = elements.filter((el) => !el.matches(FOCUS_ORDER_SELECTOR));
+    const ordered = elements
+        .filter((el) => el.matches(FOCUS_ORDER_SELECTOR))
+        .sort((a, b) => Number(a.getAttribute('data-focus-order')) - Number(b.getAttribute('data-focus-order')));
+    return [...sortByVisualPosition(unordered), ...ordered];
+};
+/**
+ * Roving-focus members use a tabindex pattern where only one member is
+ * tabbable (`tabIndex="0"`) while the others are not (`tabIndex="-1"`).
+ * This returns the index of the current tabbable member.
+ */
+const getTabbableRovingFocusIndex = (elements, overlay) => {
+    return elements.findIndex((el) => {
+        return overlay.contains(el) && isRovingFocusItem(el) && el.tabIndex >= 0;
+    });
+};
+/**
+ * Determines if the overlay's backdrop is always blocking
+ * (no background interaction).
  * Returns false if showBackdrop=false or backdropBreakpoint > 0.
  */
 const isBackdropAlwaysBlocking = (el) => {
@@ -139,7 +245,7 @@ const focusElementInOverlay = (hostToFocus, overlay) => {
  * Should NOT include: Toast
  */
 const trapKeyboardFocus = (ev, doc) => {
-    const lastOverlay = getPresentedOverlay(doc, 'ion-alert,ion-action-sheet,ion-loading,ion-modal,ion-popover');
+    const lastOverlay = getPresentedOverlay(doc, OVERLAY_FOCUS_TRAP_SELECTOR);
     const target = ev.target;
     /**
      * If no active overlay, ignore this event.
@@ -322,6 +428,174 @@ const connectListeners = (doc) => {
         doc.addEventListener('focus', (ev) => {
             trapKeyboardFocus(ev, doc);
         }, true);
+        /**
+         * Remember which roving-focus member last received focus
+         * (arrows, click, or Tab). A roving group keeps `tabIndex=0` on a
+         * single member (e.g. the checked/first radio), so the Tab trap
+         * uses this when wrapping back into the group or focusing its slot.
+         */
+        doc.addEventListener('focusin', (ev) => {
+            const lastOverlay = getPresentedOverlay(doc, OVERLAY_FOCUS_TRAP_SELECTOR);
+            if (!lastOverlay || lastOverlay.classList.contains(FOCUS_TRAP_DISABLE_CLASS)) {
+                return;
+            }
+            const target = ev.target;
+            if (!(target instanceof HTMLElement)) {
+                return;
+            }
+            const rovingHost = getRovingFocusHost(target);
+            if (rovingHost && lastOverlay.contains(rovingHost)) {
+                lastOverlay.trapLastRovingFocus = rovingHost;
+            }
+        }, true);
+        // Listen for keydown events to intercept Tab navigation.
+        // This is needed for Safari and Firefox which may skip focusable
+        // elements or allow focus to escape the overlay.
+        // It also ensures proper focus delegation for shadow DOM elements
+        // like ion-textarea.
+        doc.addEventListener('keydown', (ev) => {
+            if (ev.key !== 'Tab' && ev.key !== 'Alt+Tab')
+                return;
+            const lastOverlay = getPresentedOverlay(doc, OVERLAY_FOCUS_TRAP_SELECTOR);
+            if (!lastOverlay || lastOverlay.classList.contains(FOCUS_TRAP_DISABLE_CLASS))
+                return;
+            const activeElement = getActiveElement(doc);
+            if (activeElement === lastOverlay) {
+                ev.preventDefault();
+                focusFirstDescendant(lastOverlay);
+                return;
+            }
+            // Check if activeElement is inside the overlay (including shadow DOM)
+            const isInsideOverlay = activeElement
+                ? lastOverlay.contains(activeElement) ||
+                    (activeElement.getRootNode() instanceof ShadowRoot &&
+                        lastOverlay.contains(activeElement.getRootNode().host)) ||
+                    (lastOverlay.shadowRoot?.contains(activeElement) ?? false)
+                : false;
+            if (!isInsideOverlay)
+                return;
+            // Get all focusable elements from both light and shadow DOM
+            let allFocusable = [
+                ...lastOverlay.querySelectorAll(focusableQueryString),
+                ...(lastOverlay.shadowRoot?.querySelectorAll(focusableQueryString) || []),
+            ];
+            /**
+             * Some elements match `focusableQueryString` but are not
+             * intended tab stops (e.g. the `ion-item` wrappers a select
+             * modal renders around its options). Components opt these out
+             * with `data-focus-ignore` so Tab can move between the real
+             * controls.
+             */
+            allFocusable = allFocusable.filter((el) => !el.matches(FOCUS_IGNORE_SELECTOR));
+            /**
+             * A roving-focus group is a single tab stop: only its currently
+             * tabbable member (`tabIndex >= 0`) participates. Other
+             * focusables inside the group are not independent tab stops —
+             * this includes inactive members and focusable wrappers such as
+             * the `ion-item` that carries `ion-focusable` on behalf of a
+             * radio. Drop them so Tab moves between the group and the
+             * surrounding controls (e.g. the handle), not into the wrappers.
+             */
+            allFocusable = allFocusable.filter((el) => !isRovingFocusItem(el) || el.tabIndex >= 0);
+            /**
+             * When a component declares an explicit tab order via
+             * `data-focus-order` (e.g. a sheet modal's handle and Cancel
+             * button), reorder accordingly. Overlays that declare no order
+             * keep their DOM order.
+             */
+            if (allFocusable.some((el) => el.matches(FOCUS_ORDER_SELECTOR))) {
+                allFocusable = applyFocusOrder(allFocusable);
+            }
+            if (allFocusable.length === 0) {
+                ev.preventDefault();
+                return;
+            }
+            // Find current element's index (accounting for shadow DOM)
+            let currentIndex = activeElement
+                ? allFocusable.findIndex((el) => {
+                    if (el === activeElement)
+                        return true;
+                    if (el.shadowRoot?.contains(activeElement))
+                        return true;
+                    const rootNode = activeElement.getRootNode();
+                    return rootNode instanceof ShadowRoot && rootNode.host === el;
+                })
+                : -1;
+            /**
+             * A roving-focus group keeps `tabIndex=0` on a single member
+             * while the others are `-1`. Arrow keys can move focus onto a
+             * `tabIndex=-1` member, which `focusableQueryString` excludes,
+             * so `findIndex` yields -1 and Tab would wrap to
+             * `allFocusable[0]`. Treat focus on any group member as the
+             * group's tabbable slot so Tab goes to the next control (e.g.
+             * handle → Cancel), not back to the first member.
+             */
+            if (currentIndex < 0 && activeElement) {
+                const rovingHost = getRovingFocusHost(activeElement);
+                if (rovingHost && lastOverlay.contains(rovingHost)) {
+                    const directIndex = allFocusable.indexOf(rovingHost);
+                    if (directIndex >= 0) {
+                        currentIndex = directIndex;
+                    }
+                    else {
+                        const tabbableIndex = getTabbableRovingFocusIndex(allFocusable, lastOverlay);
+                        if (tabbableIndex >= 0) {
+                            currentIndex = tabbableIndex;
+                        }
+                    }
+                }
+            }
+            ev.preventDefault();
+            // Helper to focus an element, handling shadow DOM properly
+            const focusElement = (element) => {
+                const shadowRoot = element.shadowRoot;
+                if (shadowRoot) {
+                    const innerFocusable = shadowRoot.querySelector(focusableQueryString);
+                    if (innerFocusable && typeof element.setFocus !== 'function') {
+                        focusVisibleElement(innerFocusable);
+                        return;
+                    }
+                }
+                focusVisibleElement(element);
+            };
+            let nextIndex;
+            if (ev.shiftKey) {
+                // Shift+Tab: previous element, wrap to last if at first
+                if (currentIndex <= 0) {
+                    nextIndex = allFocusable.length - 1;
+                }
+                else {
+                    nextIndex = currentIndex - 1;
+                }
+            }
+            else {
+                // Tab: next element, wrap to first if at last
+                if (currentIndex < 0 || currentIndex >= allFocusable.length - 1) {
+                    nextIndex = 0;
+                }
+                else {
+                    nextIndex = currentIndex + 1;
+                }
+            }
+            const nextEl = allFocusable[nextIndex];
+            const overlayTrap = lastOverlay;
+            const tabbableRovingIndex = getTabbableRovingFocusIndex(allFocusable, lastOverlay);
+            /**
+             * The trap list only includes one tabbable member of a roving
+             * group (`tabIndex >= 0`), usually the checked/first radio.
+             * `focusin` tracks the real last-focused member. Use it whenever
+             * Tab would focus that slot (wrap from Cancel, Shift+Tab from
+             * handle, etc.).
+             */
+            let focusTarget = nextEl;
+            if (tabbableRovingIndex >= 0 && nextIndex === tabbableRovingIndex) {
+                const saved = overlayTrap.trapLastRovingFocus;
+                if (saved?.isConnected && lastOverlay.contains(saved) && saved !== nextEl) {
+                    focusTarget = saved;
+                }
+            }
+            focusElement(focusTarget);
+        }, true);
         // handle back-button click
         doc.addEventListener('ionBackButton', (ev) => {
             const lastOverlay = getPresentedOverlay(doc);
@@ -491,7 +765,7 @@ export const restoreRootFocusTrapAccessibility = (overlayEl) => {
     }
     applyRootLock(el);
 };
-export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation, opts) => {
+export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation, ionicEnterAnimation, opts) => {
     if (overlay.presented) {
         return;
     }
@@ -523,11 +797,15 @@ export const present = async (overlay, name, iosEnterAnimation, mdEnterAnimation
         applyRootLock(overlayEl);
     }
     overlay.willPresentShorthand?.emit();
+    const theme = getIonTheme(overlay);
     const mode = getIonMode(overlay);
+    const selectedAnimation = mode === 'ios'
+        ? iosEnterAnimation
+        : theme === 'ionic' && ionicEnterAnimation
+            ? ionicEnterAnimation
+            : mdEnterAnimation;
     // get the user's animation fn if one was provided
-    const animationBuilder = overlay.enterAnimation
-        ? overlay.enterAnimation
-        : config.get(name, mode === 'ios' ? iosEnterAnimation : mdEnterAnimation);
+    const animationBuilder = overlay.enterAnimation ? overlay.enterAnimation : config.get(name, selectedAnimation);
     const completed = await overlayAnimation(overlay, animationBuilder, overlay.el, opts);
     if (completed) {
         overlay.didPresent.emit();
@@ -701,7 +979,8 @@ export const dismiss = async (overlay, data, role, name, iosLeaveAnimation, mdLe
     return true;
 };
 const getAppRoot = (doc) => {
-    return doc.querySelector('ion-app') || doc.body;
+    const appRootSelector = config.get('appRootSelector', 'ion-app');
+    return doc.querySelector(appRootSelector) || doc.body;
 };
 const overlayAnimation = async (overlay, animationBuilder, baseEl, opts) => {
     // Make overlay visible in case it's hidden

package/dist/collection/utils/scroll-hide-controller.js

@@ -0,0 +1,178 @@
+/*!
+ * (C) Ionic http://ionicframework.com - MIT License
+ */
+import { readTask, writeTask } from "@stencil/core";
+import { getScrollElement } from "./content";
+const TOP_VISIBLE_THRESHOLD = 80;
+const SCROLL_HIDE_THRESHOLD = 60;
+const WHEEL_SUPPRESS_DURATION_MS = 80;
+const SUPPRESS_SHOW_DURATION_MS = 400;
+/**
+ * Creates a controller that manages scroll-based hide/show behavior
+ * for headers, footers, and tab bars.
+ *
+ * Listens to both wheel and scroll events. Wheel events (desktop mice)
+ * give direction instantly via deltaY. Scroll events cover touch,
+ * trackpad, and programmatic scrolling where wheel doesn't fire.
+ * A short suppression window stops them from double-processing the
+ * same gesture.
+ *
+ * When the user reverses scroll direction, we save that position as
+ * an anchor. The bar only hides after scrolling 60px past that
+ * anchor, which prevents flickering on small or jittery movements.
+ * Showing is immediate on direction change.
+ *
+ * When `options` is provided, the controller also handles the DOM
+ * setup: ResizeObserver for height tracking, CSS variable read/write,
+ * content partner/hidden class toggling, inert/aria-hidden, and
+ * full teardown cleanup. This avoids duplicating the same setup
+ * across header, footer, and tab-bar.
+ *
+ * @internal
+ * @param contentEl The content element to resolve the scroll element from.
+ * @param options Configuration for DOM setup (classes, CSS vars, a11y).
+ */
+export const createScrollHideController = async (contentEl, options) => {
+    const { el, cssVar, hiddenClass, contentPartnerClass, contentHiddenClass, shouldKeepAriaHidden } = options;
+    let controllerIsHidden = false;
+    let resizeObserver;
+    // --- DOM setup: height tracking, classes, a11y ---
+    const updateHideHeight = () => {
+        readTask(() => {
+            const heightPx = el.offsetHeight;
+            writeTask(() => {
+                el.style.setProperty(cssVar, `${heightPx}px`);
+                contentEl.style.setProperty(cssVar, `${heightPx}px`);
+            });
+        });
+    };
+    const setHidden = (hidden) => {
+        controllerIsHidden = hidden;
+        el.classList.toggle(hiddenClass, hidden);
+        if (hidden) {
+            el.setAttribute('inert', '');
+            el.setAttribute('aria-hidden', 'true');
+        }
+        else {
+            el.removeAttribute('inert');
+            if (!shouldKeepAriaHidden || !shouldKeepAriaHidden()) {
+                el.removeAttribute('aria-hidden');
+            }
+        }
+        contentEl.classList.toggle(contentHiddenClass, hidden);
+    };
+    // --- Scroll math ---
+    const scrollEl = await getScrollElement(contentEl);
+    let lastScrollPosition = 0;
+    let scrollPositionAtDirectionChange = 0;
+    let lastWheelEventTimestamp = 0;
+    let suppressShowUntil = 0;
+    const commitHide = (hidden) => {
+        if (hidden) {
+            suppressShowUntil = Date.now() + SUPPRESS_SHOW_DURATION_MS;
+        }
+        else {
+            suppressShowUntil = 0;
+        }
+        setHidden(hidden);
+    };
+    const handleWheel = (wheelEvent) => {
+        lastWheelEventTimestamp = Date.now();
+        readTask(() => {
+            const currentScrollTop = scrollEl.scrollTop;
+            // Both wheel and scroll events fire for mouse wheel input.
+            // Scroll events are suppressed for 80ms after a wheel event,
+            // but when they resume, handleScroll needs an up-to-date
+            // lastScrollPosition or it may detect the wrong direction.
+            lastScrollPosition = currentScrollTop;
+            if (currentScrollTop <= TOP_VISIBLE_THRESHOLD) {
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+                return;
+            }
+            if (wheelEvent.deltaY < 0) {
+                scrollPositionAtDirectionChange = currentScrollTop;
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+            }
+            else if (wheelEvent.deltaY > 0) {
+                const scrolledSinceDirectionChange = currentScrollTop - scrollPositionAtDirectionChange;
+                if (scrolledSinceDirectionChange >= SCROLL_HIDE_THRESHOLD && !controllerIsHidden) {
+                    writeTask(() => commitHide(true));
+                }
+            }
+        });
+    };
+    const handleScroll = () => {
+        if (Date.now() - lastWheelEventTimestamp < WHEEL_SUPPRESS_DURATION_MS) {
+            return;
+        }
+        readTask(() => {
+            const currentScrollTop = scrollEl.scrollTop;
+            if (currentScrollTop <= TOP_VISIBLE_THRESHOLD) {
+                if (controllerIsHidden) {
+                    writeTask(() => commitHide(false));
+                }
+                lastScrollPosition = currentScrollTop;
+                return;
+            }
+            if (currentScrollTop === lastScrollPosition) {
+                return;
+            }
+            const isScrollingDown = currentScrollTop > lastScrollPosition;
+            const wasScrollingDown = lastScrollPosition > scrollPositionAtDirectionChange;
+            if (isScrollingDown !== wasScrollingDown) {
+                scrollPositionAtDirectionChange = lastScrollPosition;
+            }
+            const scrolledSinceDirectionChange = Math.abs(currentScrollTop - scrollPositionAtDirectionChange);
+            const requiredScrollDistance = isScrollingDown ? SCROLL_HIDE_THRESHOLD : 0;
+            lastScrollPosition = currentScrollTop;
+            if (scrolledSinceDirectionChange < requiredScrollDistance) {
+                return;
+            }
+            const shouldHide = isScrollingDown;
+            if (shouldHide !== controllerIsHidden) {
+                if (!shouldHide && Date.now() < suppressShowUntil) {
+                    return;
+                }
+                writeTask(() => commitHide(shouldHide));
+            }
+        });
+    };
+    // --- Controller ---
+    let initialized = false;
+    const init = () => {
+        initialized = true;
+        updateHideHeight();
+        if (typeof ResizeObserver !== 'undefined') {
+            resizeObserver = new ResizeObserver(() => updateHideHeight());
+            resizeObserver.observe(el);
+        }
+        scrollEl.addEventListener('scroll', handleScroll, { passive: true });
+        scrollEl.addEventListener('wheel', handleWheel, { passive: true });
+        contentEl.classList.add(contentPartnerClass);
+    };
+    const destroy = () => {
+        if (!initialized)
+            return;
+        scrollEl.removeEventListener('scroll', handleScroll);
+        scrollEl.removeEventListener('wheel', handleWheel);
+        if (resizeObserver) {
+            resizeObserver.disconnect();
+            resizeObserver = undefined;
+        }
+        contentEl.classList.remove(contentPartnerClass, contentHiddenClass);
+        contentEl.style.removeProperty(cssVar);
+        if (controllerIsHidden) {
+            el.classList.remove(hiddenClass);
+            el.removeAttribute('inert');
+            el.removeAttribute('aria-hidden');
+            controllerIsHidden = false;
+        }
+        el.style.removeProperty(cssVar);
+    };
+    const isHidden = () => controllerIsHidden;
+    return { isHidden, init, destroy };
+};

package/dist/collection/utils/test/playwright/drag-element.js

@@ -8,7 +8,19 @@
  *
  * See https://playwright.dev/docs/api/class-mouse#mouse-move for more information.
  */
-export const dragElementBy = async (el, page, dragByX = 0, dragByY = 0, startXCoord, startYCoord, releaseDrag = true) => {
+/**
+ * Drags an element by the given number of pixels on the X and Y axes.
+ *
+ * @param el The element to drag.
+ * @param page The E2E Page object.
+ * @param dragByX The number of pixels to drag on the X axis. Negative values drag left, positive values drag right.
+ * @param dragByY The number of pixels to drag on the Y axis. Negative values drag up, positive values drag down.
+ * @param startXCoord The X coordinate to start the drag from. Defaults to the center of the element.
+ * @param startYCoord The Y coordinate to start the drag from. Defaults to the center of the element.
+ * @param releaseDrag Whether to release the drag at the end of the gesture. Defaults to `true`.
+ * @param steps The number of steps to divide the drag into. More steps reduce velocity; fewer steps increase it. Use this to control whether velocity-based thresholds (e.g. full-swipe) are triggered, particularly in Safari where gesture velocity is calculated relative to animation frames. Defaults to `10`.
+ */
+export const dragElementBy = async (el, page, dragByX = 0, dragByY = 0, startXCoord, startYCoord, releaseDrag = true, steps) => {
     const boundingBox = await el.boundingBox();
     if (!boundingBox) {
         throw new Error('Cannot get a bounding box for an element that is not visible. See https://playwright.dev/docs/api/class-locator#locator-bounding-box for more information');
@@ -33,17 +45,18 @@ export const dragElementBy = async (el, page, dragByX = 0, dragByY = 0, startXCo
         await page.evaluate(() => window.getSelection()?.removeAllRanges());
     }
     // Drag the element.
-    await moveElement(page, startX, startY, dragByX, dragByY);
+    await moveElement(page, startX, startY, dragByX, dragByY, steps);
     if (releaseDrag) {
         await page.mouse.up();
     }
 };
 /**
  * Drags an element by the given amount of pixels on the Y axis.
+ *
  * @param el The element to drag.
  * @param page The E2E Page object.
- * @param dragByY The amount of pixels to drag the element by.
- * @param startYCoord The Y coordinate to start the drag gesture at. Defaults to the center of the element.
+ * @param dragByY The number of pixels to drag on the Y axis.
+ * @param startYCoord The Y coordinate to start the drag from. Defaults to the center of the element.
  */
 export const dragElementByYAxis = async (el, page, dragByY, startYCoord) => {
     const boundingBox = await el.boundingBox();
@@ -85,8 +98,7 @@ const validateDragByY = (startY, dragByY, viewportHeight) => {
         throw new Error(`The element is being dragged past the top of the viewport. Update the dragByY value to prevent going out of bounds. A recommended value is ${recommendedDragByY}.`);
     }
 };
-const moveElement = async (page, startX, startY, dragByX = 0, dragByY = 0) => {
-    const steps = 10;
+const moveElement = async (page, startX, startY, dragByX = 0, dragByY = 0, steps = 10) => {
     const browser = page.context().browser().browserType().name();
     const viewport = page.viewportSize();
     if (viewport === null) {
@@ -101,10 +113,21 @@ const moveElement = async (page, startX, startY, dragByX = 0, dragByY = 0) => {
         const middleX = startX + (endX - startX) * (i / steps);
         const middleY = startY + (endY - startY) * (i / steps);
         await page.mouse.move(middleX, middleY);
-        // Safari needs to wait for a repaint to occur before moving the mouse again.
+        /**
+         * In Safari, gesture velocity is calculated relative to animation
+         * frames, causing velocity to accumulate faster than in other
+         * browsers. Without waiting for a repaint, consecutive `mouse.move`
+         * events arrive with ~0ms time delta and velocity never accumulates,
+         * causing gesture
+         * detection to fail.
+         */
         if (browser === 'webkit' && i % 2 === 0) {
-            // Repainting every 2 steps is enough to keep the drag gesture smooth.
-            // Anything past 4 steps will cause the drag gesture to be flaky.
+            /**
+             * Repainting every 2 steps is enough to keep the drag gesture
+             * smooth. Repainting on every step makes the test slow, and
+             * repainting every 4+ steps means Safari does not see enough
+             * frames to track the gesture reliably.
+             */
             await page.evaluate(() => new Promise(requestAnimationFrame));
         }
     }