* fix #2666 iOS auto-scroll uses visualViewport, and un-bind touch handlers

Author: adumesny

doc/CHANGES.md

@@ -5,6 +5,7 @@ Change log
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
 
+- [14.0.1 (TBD)](#1401-tbd)
 - [14.0.0 (2026-09-20)](#1400-2026-09-20)
 - [13.3.0 (2026-09-11)](#1330-2026-09-11)
 - [13.2.0 (2026-08-19)](#1320-2026-08-19)
@@ -147,6 +148,9 @@ Change log
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## 14.0.1 (TBD)
+* fix: [#2666](https://github.com/gridstack/gridstack.js/issues/2666) iOS auto-scroll uses visualViewport, and un-bind touch handlers
+
 ## 14.0.0 (2026-09-20)
 * feat: [#754](https://github.com/gridstack/gridstack.js/issues/754), [#2866](https://github.com/gridstack/gridstack.js/issues/2866) new `mode?: 'top' | 'float' | 'list' | 'compact'` - items are continuously re-flowed in sequential (row-major) order, like a re-orderable list: dragging, resizing, adding or removing an item re-flows everyone else instead of pushing them down, and dropping an item on another takes its place. See new
 [list.html](https://gridstackjs.com/demo/list.html) demo.

spec/dd-draggable-touch-spec.ts

@@ -0,0 +1,65 @@
+/**
+ * #2666 - touch drag listener lifetime + iOS visible-viewport clipping
+ */
+import { Utils } from '../src/utils';
+
+// force the touch code path (jsdom has no ontouchstart so isTouch is false by default)
+vi.mock('../src/dd-touch', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/dd-touch')>();
+  return { ...actual, isTouch: true };
+});
+
+describe('2666 touch drag >', () => {
+  'use strict';
+
+  it('un-binds the touch handlers it bound, on the same element', async () => {
+    const { DDDraggable } = await import('../src/dd-draggable');
+    const el = document.createElement('div');
+    el.className = 'grid-stack-item';
+    document.body.appendChild(el);
+
+    const added: [string, unknown, unknown][] = [];
+    const removed: [string, unknown, unknown][] = [];
+    const origAdd = el.addEventListener.bind(el);
+    const origRemove = el.removeEventListener.bind(el);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    el.addEventListener = ((t: string, f: any, o: any) => { added.push([t, f, o]); return origAdd(t, f, o); }) as any;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    el.removeEventListener = ((t: string, f: any, o: any) => { removed.push([t, f, o]); return origRemove(t, f, o); }) as any;
+
+    const dd = new DDDraggable(el, {});
+    const down = new MouseEvent('mousedown', { button: 0, bubbles: true });
+    Object.defineProperty(down, 'currentTarget', { value: el });
+    Object.defineProperty(down, 'target', { value: el });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (dd as any)._mouseDown(down);
+
+    const touchAdds = added.filter(([t]) => t.startsWith('touch') && t !== 'touchstart');
+    expect(touchAdds.length).toBe(3); // touchmove, touchend, touchcancel
+
+    // _mouseUp is a *document* handler, so its currentTarget is not `el` - it must still clean up `el`
+    const up = new MouseEvent('mouseup', { bubbles: true });
+    Object.defineProperty(up, 'currentTarget', { value: document });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (dd as any)._mouseUp(up);
+
+    for (const [type, fn, opt] of touchAdds) {
+      const match = removed.find(([t, f, o]) => t === type && f === fn && !!o === !!opt);
+      expect(match, `${type} listener was never removed from the element it was added to`).toBeTruthy();
+    }
+
+    dd.destroy();
+    document.body.removeChild(el);
+  });
+
+  it('getVisibleViewport() uses visualViewport (iOS bars/pinch-zoom) with innerHeight fallback', () => {
+    const orig = window.visualViewport;
+    Object.defineProperty(window, 'visualViewport', { value: { offsetTop: 30, height: 500 }, configurable: true });
+    expect(Utils.getVisibleViewport()).toEqual({ top: 30, bottom: 530 });
+
+    Object.defineProperty(window, 'visualViewport', { value: undefined, configurable: true });
+    expect(Utils.getVisibleViewport()).toEqual({ top: 0, bottom: window.innerHeight });
+
+    Object.defineProperty(window, 'visualViewport', { value: orig, configurable: true });
+  });
+});

src/dd-draggable.ts

@@ -62,6 +62,8 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
     xOffset: 0,
     yOffset: 0
   };
+  /** @internal element we bound the touch handlers to in _mouseDown(), so _mouseUp() can un-bind the same one */
+  protected _touchTarget?: HTMLElement;
   /** @internal auto-scroll animation variables */
   protected _autoScrollAnimId?: number;
   protected _autoScrollContainer?: HTMLElement;
@@ -222,9 +224,13 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
     document.addEventListener('mousemove', this._mouseMove, { capture: true, passive: true }); // true=capture, not bubble
     document.addEventListener('mouseup', this._mouseUp as EventListener, true);
     if (isTouch && e.currentTarget) {
-      (e.currentTarget as HTMLElement).addEventListener('touchmove', touchmove);
-      (e.currentTarget as HTMLElement).addEventListener('touchend', touchend);
-      (e.currentTarget as HTMLElement).addEventListener('touchcancel', touchend); // browser aborting on us, clean up too
+      // remember what we bound to: _mouseUp() is a document handler so its own currentTarget is
+      // NOT this element, and these were added bubbling - removing with capture=true never matched,
+      // leaking a handler per drag that then replayed each touchmove N times over (#2666).
+      this._touchTarget = e.currentTarget as HTMLElement;
+      this._touchTarget.addEventListener('touchmove', touchmove);
+      this._touchTarget.addEventListener('touchend', touchend);
+      this._touchTarget.addEventListener('touchcancel', touchend); // browser aborting on us, clean up too
     }
     if (DDTouch.wasDelayed) {
       // the long-press wait just elapsed - signal the item is now armed & ready to drag
@@ -306,10 +312,11 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
     this.el.classList.remove('ui-draggable-armed');
     document.removeEventListener('mousemove', this._mouseMove, true);
     document.removeEventListener('mouseup', this._mouseUp as EventListener, true);
-    if (isTouch && e.currentTarget) { // destroy() during nested grid call us again wit fake _mouseUp
-      e.currentTarget.removeEventListener('touchmove', touchmove as EventListener, true);
-      e.currentTarget.removeEventListener('touchend', touchend as EventListener, true);
-      e.currentTarget.removeEventListener('touchcancel', touchend as EventListener, true);
+    if (isTouch && this._touchTarget) { // destroy() during nested grid call us again wit fake _mouseUp
+      this._touchTarget.removeEventListener('touchmove', touchmove as EventListener);
+      this._touchTarget.removeEventListener('touchend', touchend as EventListener);
+      this._touchTarget.removeEventListener('touchcancel', touchend as EventListener);
+      delete this._touchTarget;
     }
     if (this.dragging) {
       delete this.dragging;
@@ -512,10 +519,11 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
   protected _getClipping(el: HTMLElement, scrollEl: HTMLElement): number {
     const elRect = el.getBoundingClientRect();
     const scrollRect = scrollEl.getBoundingClientRect();
-    const viewportH = window.innerHeight || document.documentElement.clientHeight;
+    // what's really on screen, NOT window.innerHeight which sits under iOS's overlaying tool bars (#2666)
+    const view = Utils.getVisibleViewport();
     if (elRect.bottom < scrollRect.top || elRect.top > scrollRect.bottom) return 0; // fully outside
-    const clippedBelow = elRect.bottom - Math.min(scrollRect.bottom, viewportH);
-    const clippedAbove = elRect.top - Math.max(scrollRect.top, 0);
+    const clippedBelow = elRect.bottom - Math.min(scrollRect.bottom, view.bottom);
+    const clippedAbove = elRect.top - Math.max(scrollRect.top, view.top);
     if (clippedAbove < 0) return clippedAbove;
     if (clippedBelow > 0) return clippedBelow;
     return 0;
@@ -530,8 +538,8 @@ export class DDDraggable extends DDBaseImplement implements HTMLElementExtendOpt
     if (clipping === 0) { this._stopScrolling(); return; }
 
     if (!this._autoScrollMaxSpeed) {
-      const viewportH = window.innerHeight || document.documentElement.clientHeight;
-      this._autoScrollMaxSpeed = Math.max(viewportH / 150, 4);
+      const view = Utils.getVisibleViewport();
+      this._autoScrollMaxSpeed = Math.max((view.bottom - view.top) / 150, 4);
     }
     const absPx = Math.abs(clipping);
     const speed = Math.min(absPx * 0.5, this._autoScrollMaxSpeed);

src/utils.ts

@@ -520,6 +520,18 @@ export class Utils {
     }
   }
 
+  /** @internal V bounds (viewport coordinates) of what the user can actually see.
+   * Use this instead of `window.innerHeight` for clipping math: on iOS Safari `innerHeight` is the
+   * *layout* viewport, which extends underneath the overlaying URL/tool bars (and ignores pinch-zoom),
+   * so an item hidden behind the bottom bar still measured as fully visible and auto-scroll never
+   * kicked in - see #2666. `visualViewport` reports what is truly on screen on every browser. */
+  static getVisibleViewport(): { top: number, bottom: number } {
+    const vv = typeof window !== 'undefined' ? window.visualViewport : undefined;
+    if (vv) return { top: vv.offsetTop, bottom: vv.offsetTop + vv.height };
+    const h = window.innerHeight || document.documentElement.clientHeight;
+    return { top: 0, bottom: h };
+  }
+
   /** @internal returns the passed element if vertically scrollable, else the closest parent that will, up to the entire document scrolling element */
   static getScrollElement(el?: HTMLElement): HTMLElement {
     if (!el) return document.scrollingElement as HTMLElement || document.documentElement; // IE support