@ionic/core 9.0.1-nightly.20260821 → 9.0.1-nightly.20260824

package/dist/collection/components/picker-column/picker-column.js

@@ -20,6 +20,12 @@ export class PickerColumn {
         this.isColumnVisible = false;
         this.canExitInputMode = true;
         this.updateValueTextOnScroll = false;
+        this.isUserScroll = false;
+        /**
+         * The haptics for the wheel picker are an iOS-only feature. As a result,
+         * they should be disabled on Android.
+         */
+        this.enableHaptics = false;
         this.ariaLabel = null;
         this.isActive = false;
         /**
@@ -51,6 +57,12 @@ export class PickerColumn {
                      */
                     this.canExitInputMode = canExitInputMode;
                     this.updateValueTextOnScroll = false;
+                    /**
+                     * This scroll takes over from whatever the user was doing, so an outside
+                     * press must not commit an option the column is only passing through.
+                     */
+                    this.isUserScroll = false;
+                    this.stopWatchingForOutsidePress();
                     scrollEl.scroll({
                         top,
                         left: 0,
@@ -105,6 +117,117 @@ export class PickerColumn {
             }
             this.isActive = state;
         };
+        this.clearScrollEndTimeout = () => {
+            if (this.scrollEndTimeout) {
+                clearTimeout(this.scrollEndTimeout);
+                this.scrollEndTimeout = undefined;
+            }
+        };
+        /**
+         * Resets the idle timer that commits the centered option.
+         */
+        this.resetScrollEndTimeout = () => {
+            this.clearScrollEndTimeout();
+            this.scrollEndTimeout = setTimeout(this.settle, SCROLL_END_DELAY);
+        };
+        /**
+         * Capture so the column still commits if an application's own pointerdown
+         * handler stops the event before it reaches the document.
+         */
+        this.watchForOutsidePress = () => {
+            doc?.addEventListener('pointerdown', this.onPointerDownOutside, { capture: true });
+        };
+        this.stopWatchingForOutsidePress = () => {
+            doc?.removeEventListener('pointerdown', this.onPointerDownOutside, { capture: true });
+        };
+        /**
+         * Resets everything the current scroll interaction is holding, so nothing
+         * pending on it can commit later.
+         */
+        this.discardScroll = () => {
+            this.stopWatchingForOutsidePress();
+            this.clearScrollEndTimeout();
+            this.scrollEndCallback = undefined;
+            this.centeredOption = undefined;
+            this.haltedAtScrollTop = undefined;
+            this.isScrolling = false;
+            this.isUserScroll = false;
+            this.canExitInputMode = true;
+        };
+        /**
+         * Commits the option that is currently centered under the highlight and ends
+         * the scroll interaction.
+         */
+        this.settle = () => {
+            const { centeredOption } = this;
+            this.clearScrollEndTimeout();
+            this.stopWatchingForOutsidePress();
+            this.isUserScroll = false;
+            this.isScrolling = false;
+            this.updateValueTextOnScroll = true;
+            this.enableHaptics && hapticSelectionEnd();
+            /**
+             * Certain tasks (such as those that
+             * cause re-renders) should only be done
+             * once scrolling has finished, otherwise
+             * flickering may occur.
+             */
+            const { scrollEndCallback } = this;
+            if (scrollEndCallback) {
+                scrollEndCallback();
+                this.scrollEndCallback = undefined;
+            }
+            /**
+             * Reset this flag as the
+             * next scroll interaction could
+             * be a scroll from the user. In this
+             * case, we should exit input mode.
+             */
+            this.canExitInputMode = true;
+            if (centeredOption !== undefined) {
+                // Cleared here so a later scroll that centers nothing cannot fall back on it.
+                this.centeredOption = undefined;
+                if (centeredOption.isConnected) {
+                    this.setValue(centeredOption.value);
+                }
+            }
+        };
+        /**
+         * Commits the option the user can see when they press anything outside of the
+         * column during a scroll they started. This runs on pointerdown rather than
+         * click so the value is up to date by the time an application's own click
+         * handler (a Save button, for example) reads it.
+         */
+        this.onPointerDownOutside = (ev) => {
+            const { centeredOption, parentEl, scrollEl } = this;
+            if (!this.isScrolling) {
+                return;
+            }
+            /**
+             * The column can live in another component's Shadow DOM, where a document
+             * listener sees the target retargeted to the outer host. The composed path
+             * is the only reliable way to tell a press on the column apart.
+             */
+            const path = ev.composedPath();
+            /**
+             * A press anywhere in the parent picker counts as inside, so reaching for a
+             * sibling wheel leaves this column coasting.
+             */
+            if (path.includes(this.el) || (parentEl != null && path.includes(parentEl))) {
+                return;
+            }
+            /**
+             * Landing on the centered option halts the in-flight momentum scroll, so the
+             * committed value and the option the user is left looking at agree. The
+             * option list can be replaced mid-scroll, and a detached option has no
+             * offset to center on.
+             */
+            if (centeredOption !== undefined && centeredOption.isConnected) {
+                this.centerPickerItemInView(centeredOption, false, false);
+                this.haltedAtScrollTop = scrollEl?.scrollTop;
+            }
+            this.settle();
+        };
         /**
          * When the column scrolls, the component
          * needs to determine which item is centered
@@ -112,27 +235,42 @@ export class PickerColumn {
          * the item object.
          */
         this.initializeScrollListener = () => {
-            /**
-             * The haptics for the wheel picker are
-             * an iOS-only feature. As a result, they should
-             * be disabled on Android.
-             */
-            const enableHaptics = isPlatform('ios');
+            this.enableHaptics = isPlatform('ios');
             const { el, scrollEl } = this;
-            let timeout;
             let activeEl = this.activeItem;
             const scrollCallback = () => {
                 raf(() => {
-                    if (!scrollEl)
+                    /**
+                     * This frame cannot be cancelled, and moving the column disconnects it
+                     * without the observer reporting a change, so this checks live state.
+                     */
+                    if (!this.el.isConnected || !this.isColumnVisible || !scrollEl)
                         return;
-                    if (timeout) {
-                        clearTimeout(timeout);
-                        timeout = undefined;
+                    const { haltedAtScrollTop } = this;
+                    if (haltedAtScrollTop !== undefined) {
+                        /**
+                         * Still at the halted position, so this frame is the halt landing
+                         * rather than the wheel moving, and re-arming would start a second
+                         * commit cycle.
+                         */
+                        if (Math.abs(scrollEl.scrollTop - haltedAtScrollTop) <= HALT_TOLERANCE)
+                            return;
+                        this.haltedAtScrollTop = undefined;
                     }
+                    // Armed before the early returns below, so a scroll never ends uncommitted.
+                    this.resetScrollEndTimeout();
                     if (!this.isScrolling) {
-                        enableHaptics && hapticSelectionStart();
+                        this.enableHaptics && hapticSelectionStart();
                         this.isScrolling = true;
                     }
+                    /**
+                     * Only a user-driven scroll holds an uncommitted selection. Checked every
+                     * frame because the user can take hold of the wheel mid-scroll, and
+                     * re-adding the same listener is a no-op.
+                     */
+                    if (this.isUserScroll) {
+                        this.watchForOutsidePress();
+                    }
                     /**
                      * Select item in the center of the column
                      * which is the month/year that we want to select
@@ -192,18 +330,23 @@ export class PickerColumn {
                             newActiveElement = fallbackActiveElement;
                         }
                     }
-                    if (activeEl !== undefined) {
-                        this.setPickerItemActiveState(activeEl, false);
-                    }
+                    /**
+                     * A scroll can land with no selectable option centered, such as an
+                     * overscroll bounce briefly centering the empty padding rows. Keep the
+                     * current selection until an option is centered again.
+                     */
                     if (newActiveElement === undefined || newActiveElement.disabled) {
                         return;
                     }
+                    if (activeEl !== undefined) {
+                        this.setPickerItemActiveState(activeEl, false);
+                    }
                     /**
                      * If we are selecting a new value,
                      * we need to run haptics again.
                      */
                     if (newActiveElement !== activeEl) {
-                        enableHaptics && hapticSelectionChanged();
+                        this.enableHaptics && hapticSelectionChanged();
                         if (this.canExitInputMode) {
                             /**
                              * The native iOS wheel picker
@@ -235,32 +378,14 @@ export class PickerColumn {
                     if (this.updateValueTextOnScroll) {
                         this.assistiveFocusable?.setAttribute('aria-valuetext', this.getOptionValueText(newActiveElement));
                     }
-                    timeout = setTimeout(() => {
-                        this.isScrolling = false;
-                        this.updateValueTextOnScroll = true;
-                        enableHaptics && hapticSelectionEnd();
-                        /**
-                         * Certain tasks (such as those that
-                         * cause re-renders) should only be done
-                         * once scrolling has finished, otherwise
-                         * flickering may occur.
-                         */
-                        const { scrollEndCallback } = this;
-                        if (scrollEndCallback) {
-                            scrollEndCallback();
-                            this.scrollEndCallback = undefined;
-                        }
-                        /**
-                         * Reset this flag as the
-                         * next scroll interaction could
-                         * be a scroll from the user. In this
-                         * case, we should exit input mode.
-                         */
-                        this.canExitInputMode = true;
-                        this.setValue(newActiveElement.value);
-                    }, 250);
+                    this.centeredOption = newActiveElement;
                 });
             };
+            const userScrollCallback = () => {
+                this.isUserScroll = true;
+                // Taking hold of the wheel ends the halt even if it has not moved yet.
+                this.haltedAtScrollTop = undefined;
+            };
             /**
              * Wrap this in an raf so that the scroll callback
              * does not fire when component is initially shown.
@@ -269,8 +394,19 @@ export class PickerColumn {
                 if (!scrollEl)
                     return;
                 scrollEl.addEventListener('scroll', scrollCallback);
+                scrollEl.addEventListener('pointerdown', userScrollCallback);
+                scrollEl.addEventListener('wheel', userScrollCallback, { passive: true });
+                /**
+                 * A `pointerdown` fires once per touch, so a drag that pauses long enough
+                 * to commit would look like a scroll the column started. A `touchmove`
+                 * keeps arriving while the finger moves.
+                 */
+                scrollEl.addEventListener('touchmove', userScrollCallback, { passive: true });
                 this.destroyScrollListener = () => {
                     scrollEl.removeEventListener('scroll', scrollCallback);
+                    scrollEl.removeEventListener('pointerdown', userScrollCallback);
+                    scrollEl.removeEventListener('wheel', userScrollCallback);
+                    scrollEl.removeEventListener('touchmove', userScrollCallback);
                 };
             });
         };
@@ -455,6 +591,14 @@ export class PickerColumn {
             }
             else {
                 this.isColumnVisible = false;
+                /**
+                 * The pending timer still runs so it resets the scroll state, but the
+                 * option it would have committed is dropped. A column the user cannot
+                 * see should not change its value.
+                 */
+                this.stopWatchingForOutsidePress();
+                this.centeredOption = undefined;
+                this.haltedAtScrollTop = undefined;
                 if (this.destroyScrollListener) {
                     this.destroyScrollListener();
                     this.destroyScrollListener = undefined;
@@ -525,6 +669,13 @@ export class PickerColumn {
     connectedCallback() {
         this.ariaLabel = this.el.getAttribute('aria-label') ?? 'Select a value';
     }
+    disconnectedCallback() {
+        /**
+         * A pending settle would otherwise commit a value on a column that is no
+         * longer in the DOM.
+         */
+        this.discardScroll();
+    }
     get activeItem() {
         const { value } = this;
         const options = Array.from(this.el.querySelectorAll('ion-picker-column-option'));
@@ -542,14 +693,14 @@ export class PickerColumn {
     render() {
         const { color, disabled, isActive, numericInput } = this;
         const mode = getIonMode(this);
-        return (h(Host, { key: '78b46ad10d88ea1bb43ca8c36748767912f03224', class: createColorClasses(color, {
+        return (h(Host, { key: '60a893619d0b01fba53fbccef67a10d533a22657', class: createColorClasses(color, {
                 [mode]: true,
                 ['picker-column-active']: isActive,
                 ['picker-column-numeric-input']: numericInput,
                 ['picker-column-disabled']: disabled,
-            }) }, h("slot", { key: '761e501df77f7de896ffb3ebb99ebf88c5c3bf70', name: "prefix" }), h("div", { key: '9f4caaeef8ab704522a85f30876d371712f47c5c', class: "picker-opts", ref: (el) => {
+            }) }, h("slot", { key: '79f1e047f89c5ec916ed02efaac56ef3f73b8969', name: "prefix" }), h("div", { key: 'c45c86e88353a196ff38159f40f390bc27852c9e', class: "picker-opts", ref: (el) => {
                 this.scrollEl = el;
-            }, role: "slider", tabindex: this.disabled ? undefined : 0, "aria-label": this.ariaLabel, "aria-valuemin": 0, "aria-valuemax": 0, "aria-valuenow": 0, "aria-valuetext": this.getOptionValueText(this.activeItem), "aria-orientation": "vertical", onKeyDown: (ev) => this.onKeyDown(ev) }, h("div", { key: '9d3533436aba6c61c93f65f84a077fba832194a0', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: '3f18d3a47361f06f55321b65fdf5742a61722b26', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: 'eac0d20ab8c533ef829875e323e93e1ee2067d6d', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("slot", { key: '92e25989ef41cf6f910c73238e1a0a5ac03f1c1f' }), h("div", { key: '33a84644ebdc84108b44a8e3a129b54e824939c8', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: '128ad61a3a68c7ff2d2e44a6e968424fcc608a15', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: '6e4d59a4f75befcbbf47279a263f28a69b12dbbd', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0")), h("slot", { key: '3c6621b64438792a3024c90e3d9916a0a3614506', name: "suffix" })));
+            }, role: "slider", tabindex: this.disabled ? undefined : 0, "aria-label": this.ariaLabel, "aria-valuemin": 0, "aria-valuemax": 0, "aria-valuenow": 0, "aria-valuetext": this.getOptionValueText(this.activeItem), "aria-orientation": "vertical", onKeyDown: (ev) => this.onKeyDown(ev) }, h("div", { key: 'e02d76752f5d3dd4cd2846fbc28645f1508a4b49', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: 'd577bcbadc530970b2781692b050811633625c5a', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: 'c89e78c3a896bc1f55b922d01df16fdbb1259bdd', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("slot", { key: '6c597ff899692597432ee2aa0b42de53b86deed4' }), h("div", { key: '91686ed94f14c47647836ed4d63e54b5c54ee3b9', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: '2ff058c6d0e8cef4e143c2d848f9a52684579af1', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0"), h("div", { key: 'bc7386bec6fced36e44084a7a137b3fe6506c996', class: "picker-item-empty", "aria-hidden": "true" }, "\u00A0")), h("slot", { key: '8835fd3f4e025bce964e6f05984c9aaadc20d7fb', name: "suffix" })));
     }
     static get is() { return "ion-picker-column"; }
     static get encapsulation() { return "shadow"; }
@@ -773,3 +924,16 @@ export class PickerColumn {
     }
 }
 const PICKER_ITEM_ACTIVE_CLASS = 'option-active';
+/**
+ * How long the column must be idle before the centered option is treated as
+ * the user's selection. Replaceable by the `scrollend` event once that is
+ * supported everywhere (https://caniuse.com/?search=scrollend).
+ */
+const SCROLL_END_DELAY = 250;
+/**
+ * How far, in pixels, the column may report from where it was halted and still
+ * count as having stayed there. Centering targets a position between two snap
+ * points, so mandatory snapping corrects it by half the column height less
+ * three option heights: 2px at the default sizes.
+ */
+const HALT_TOLERANCE = 2;