handsontable 18.0.0 → 18.1.0-rc7

package/helpers/dom/element.js

@@ -54,6 +54,9 @@ _export(exports, {
     get getCssTransform () {
         return getCssTransform;
     },
+    get getDeepActiveElement () {
+        return getDeepActiveElement;
+    },
     get getFractionalScalingCompensation () {
         return getFractionalScalingCompensation;
     },
@@ -90,6 +93,9 @@ _export(exports, {
     get getSelectionText () {
         return getSelectionText;
     },
+    get getShadowHostChain () {
+        return getShadowHostChain;
+    },
     get getStyle () {
         return getStyle;
     },
@@ -165,6 +171,9 @@ _export(exports, {
     get matchesCSSRules () {
         return matchesCSSRules;
     },
+    get missingSanitizerMessage () {
+        return missingSanitizerMessage;
+    },
     get observeVisibilityChangeOnce () {
         return observeVisibilityChangeOnce;
     },
@@ -498,6 +507,9 @@ function empty(element) {
 }
 const HTML_CHARACTERS = /(<([^>]*)>|&([^;]*);)/;
 const SANITIZER_WARN_KEY = 'sanitizer';
+function missingSanitizerMessage(context) {
+    return `HTML content is being written to the DOM ("${context}") without a sanitizer. ` + 'Configure the "sanitizer" option to prevent XSS vulnerabilities.';
+}
 /**
  * Default scope used when a caller writes raw HTML without supplying a per-instance
  * scope. Keeps the warning to once per process for such callers.
@@ -506,13 +518,17 @@ function fastInnerHTML(element, content, sanitizer = true, context = 'innerHTML'
     if (HTML_CHARACTERS.test(content)) {
         let sanitized;
         if (typeof sanitizer === 'function') {
-            sanitized = sanitizer(content, context);
+            // `?? ''` rather than `?? content`: a sanitizer that returns nothing for input it strips
+            // entirely must not have the raw input written back, which would undo the sanitizing. The
+            // declared return type is `string`, but JavaScript callers are not held to it, and without
+            // this guard the literal word "undefined" reaches the DOM.
+            sanitized = sanitizer(content, context) ?? '';
         } else {
             // `false` means the caller renders raw HTML deliberately (for example, the `html` cell type).
             // Any other non-function value (the default `true`) is an implicit raw write, so nudge once
             // toward configuring a sanitizer to prevent XSS.
             if (sanitizer !== false) {
-                (0, _console.warnOnce)(scope, SANITIZER_WARN_KEY, `HTML content is being written to the DOM ("${context}") without a sanitizer. ` + 'Configure the "sanitizer" option to prevent XSS vulnerabilities.');
+                (0, _console.warnOnce)(scope, SANITIZER_WARN_KEY, missingSanitizerMessage(context));
             }
             sanitized = content;
         }
@@ -674,28 +690,74 @@ function getMaximumScrollTop(element) {
 function getMaximumScrollLeft(element) {
     return element.scrollWidth - element.clientWidth;
 }
+const OVERFLOW_TRIMMING_VALUES = [
+    'scroll',
+    'hidden',
+    'auto',
+    'clip'
+];
+const OVERFLOW_CONCRETE_VALUES = [
+    'visible',
+    'clip',
+    'hidden',
+    'scroll',
+    'auto',
+    'overlay'
+];
+/**
+ * Checks whether a single overflow axis traps the table on that axis.
+ *
+ * `overflow: clip` establishes no scroll port. When an axis is `clip` while the perpendicular axis
+ * stays `visible`, it does not trap the table's scroll — the table still scrolls with the window on
+ * the visible axis. A width-constrained, window-scrolled table sets `overflow-x: clip` on its root
+ * (see core.ts, DEV-1025); treating that root as the trimming container drops the overlays out of
+ * window-scroll mode (frozen rows stop pinning, vertical virtualization stops). Such a single-axis
+ * clip must not qualify the axis as trimming.
+ *
+ * @param {string} axis The `overflow-x`/`overflow-y` value of the axis being tested.
+ * @param {string} perpendicular The `overflow` value of the other axis.
+ * @returns {boolean}
+ */ function overflowAxisTraps(axis, perpendicular) {
+    return OVERFLOW_TRIMMING_VALUES.includes(axis) && !(axis === 'clip' && (perpendicular === 'visible' || perpendicular === ''));
+}
+/**
+ * Resolves the effective `overflow-x`/`overflow-y` of an element, preferring inline styles.
+ *
+ * The inline `overflow` shorthand can carry two values (`overflow: clip visible` → x, y). Some
+ * engines (jsdom) neither split that shorthand into `overflowX`/`overflowY` nor reflect it in the
+ * computed style, so the shorthand string is parsed directly. An inline value is only preferred when
+ * it is a concrete overflow keyword; a global keyword (`inherit`, `initial`, `revert`, `unset`) or
+ * any other non-concrete value falls back to the computed style, which resolves it to the real value
+ * (e.g. an inherited `auto`). Otherwise an inline `inherit` would be read literally and miss the
+ * scroll value it inherits.
+ *
+ * @param {HTMLElement} el The element to read overflow from.
+ * @param {CSSStyleDeclaration} computedStyle The element's computed style.
+ * @returns {{ x: string, y: string }}
+ */ function resolveOverflowAxes(el, computedStyle) {
+    const shorthand = el.style.overflow.split(/\s+/).filter(Boolean);
+    const [shorthandX = '', shorthandY = shorthandX] = shorthand;
+    const resolveAxis = (inlineAxis, shorthandAxis, computedProperty)=>{
+        const inline = inlineAxis || shorthandAxis;
+        return OVERFLOW_CONCRETE_VALUES.includes(inline) ? inline : computedStyle.getPropertyValue(computedProperty);
+    };
+    return {
+        x: resolveAxis(el.style.overflowX, shorthandX, 'overflow-x'),
+        y: resolveAxis(el.style.overflowY, shorthandY, 'overflow-y')
+    };
+}
 function getTrimmingContainer(base) {
     const rootDocument = base.ownerDocument;
     const rootWindow = rootDocument.defaultView;
     let el = base.parentElement;
     while(el && el.style && rootDocument.body !== el){
-        if (el.style.overflow !== 'visible' && el.style.overflow !== '') {
-            return el;
-        }
         if (rootWindow) {
-            const computedStyle = rootWindow.getComputedStyle(el);
-            const allowedProperties = [
-                'scroll',
-                'hidden',
-                'auto',
-                'clip'
-            ];
-            const property = computedStyle.getPropertyValue('overflow');
-            const propertyY = computedStyle.getPropertyValue('overflow-y');
-            const propertyX = computedStyle.getPropertyValue('overflow-x');
-            if (allowedProperties.includes(property) || allowedProperties.includes(propertyY) || allowedProperties.includes(propertyX)) {
+            const { x, y } = resolveOverflowAxes(el, rootWindow.getComputedStyle(el));
+            if (overflowAxisTraps(x, y) || overflowAxisTraps(y, x)) {
                 return el;
             }
+        } else if (el.style.overflow !== 'visible' && el.style.overflow !== '') {
+            return el;
         }
         el = el.parentElement;
     }
@@ -917,7 +979,7 @@ function isOutsideInput(element) {
     return isInput(element) && 'hotInput' in element.dataset === false;
 }
 function selectElementIfAllowed(element) {
-    const activeElement = element.ownerDocument.activeElement;
+    const activeElement = getDeepActiveElement(element.ownerDocument);
     if (isHTMLElement(activeElement) && !isOutsideInput(activeElement) && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
         element.select();
     }
@@ -935,6 +997,7 @@ function observeVisibilityChangeOnce(elementToBeObserved, callback) {
         });
     });
     visibilityObserver.observe(elementToBeObserved);
+    return visibilityObserver;
 }
 function makeElementContentEditableAndSelectItsContent(element, invisibleSelection = true, ariaHidden = true) {
     const ownerDocument = element.ownerDocument;
@@ -982,7 +1045,30 @@ function isHTMLInputElement(element) {
     return element.tagName === 'INPUT';
 }
 function isShadowRoot(node) {
-    return node.nodeType === Node.DOCUMENT_FRAGMENT_NODE && 'host' in node;
+    if (typeof node !== 'object' || node === null) {
+        return false;
+    }
+    return 'nodeType' in node && node.nodeType === Node.DOCUMENT_FRAGMENT_NODE && 'host' in node;
+}
+function getShadowHostChain(node) {
+    const hosts = [];
+    let rootNode = node.getRootNode();
+    while(isShadowRoot(rootNode)){
+        const { host } = rootNode;
+        if (!isHTMLElement(host)) {
+            break;
+        }
+        hosts.push(host);
+        rootNode = host.getRootNode();
+    }
+    return hosts;
+}
+function getDeepActiveElement(rootDocument) {
+    let element = rootDocument.activeElement;
+    while(element?.shadowRoot?.activeElement){
+        element = element.shadowRoot.activeElement;
+    }
+    return element;
 }
 function getChildEl(parent, index) {
     const node = parent.childNodes[index];

package/helpers/dom/element.mjs

@@ -410,6 +410,21 @@ export const HTML_CHARACTERS = /(<([^>]*)>|&([^;]*);)/;
  * write surfaces (headers, context menu, dialogs, notifications, editors)
  * collapse into a single warning per Handsontable instance.
  */ export const SANITIZER_WARN_KEY = 'sanitizer';
+/**
+ * Builds the missing-sanitizer warning. Every surface that writes raw HTML uses this, whether it
+ * goes through `fastInnerHTML` or sanitizes a string first (`utils/sanitizer.ts`), so the wording
+ * cannot drift between them.
+ *
+ * It lives here rather than beside its second caller because `utils/sanitizer.ts` already imports
+ * from this module, and the reverse direction would be a cycle. That makes it public through
+ * `Handsontable.dom`, like `HTML_CHARACTERS` and `SANITIZER_WARN_KEY` above it - accepted
+ * deliberately: it is a pure string builder, and it is useful to anyone writing their own sink.
+ *
+ * @param {string} context The write surface that is about to receive raw HTML.
+ * @returns {string} The warning message.
+ */ export function missingSanitizerMessage(context) {
+    return `HTML content is being written to the DOM ("${context}") without a sanitizer. ` + 'Configure the "sanitizer" option to prevent XSS vulnerabilities.';
+}
 /**
  * Default scope used when a caller writes raw HTML without supplying a per-instance
  * scope. Keeps the warning to once per process for such callers.
@@ -419,24 +434,28 @@ export const HTML_CHARACTERS = /(<([^>]*)>|&([^;]*);)/;
  *
  * @param {HTMLElement} element An element to write into.
  * @param {string} content The text to write.
- * @param {boolean|function(string, string): string} [sanitizer] When a function, use it as the sanitizer; when `false`,
+ * @param {boolean|function(string, SanitizerContext): string} [sanitizer] When a function, use it as the sanitizer; when `false`,
  * write the content as raw HTML on purpose (no warning); when `true` (the default), write the content as raw HTML and
  * warn once that no sanitizer is configured.
- * @param {string} [context] The sanitization context passed as the second argument to a custom sanitizer function, and
+ * @param {SanitizerContext} [context] The sanitization context passed as the second argument to a custom sanitizer function, and
  * used in the missing-sanitizer warning to identify the write surface.
- * @param {object} [scope] Object the "warn once" state is bound to (for example, `hot.rootGridElement`), so the warning
- * is shown at most once per Handsontable instance.
+ * @param {object} [scope] Object the "warn once" state is bound to (`hot.rootElement` at every call site
+ * inside the grid), so the warning is shown at most once per Handsontable instance.
  */ export function fastInnerHTML(element, content, sanitizer = true, context = 'innerHTML', scope = defaultSanitizerWarnScope) {
     if (HTML_CHARACTERS.test(content)) {
         let sanitized;
         if (typeof sanitizer === 'function') {
-            sanitized = sanitizer(content, context);
+            // `?? ''` rather than `?? content`: a sanitizer that returns nothing for input it strips
+            // entirely must not have the raw input written back, which would undo the sanitizing. The
+            // declared return type is `string`, but JavaScript callers are not held to it, and without
+            // this guard the literal word "undefined" reaches the DOM.
+            sanitized = sanitizer(content, context) ?? '';
         } else {
             // `false` means the caller renders raw HTML deliberately (for example, the `html` cell type).
             // Any other non-function value (the default `true`) is an implicit raw write, so nudge once
             // toward configuring a sanitizer to prevent XSS.
             if (sanitizer !== false) {
-                warnOnce(scope, SANITIZER_WARN_KEY, `HTML content is being written to the DOM ("${context}") without a sanitizer. ` + 'Configure the "sanitizer" option to prevent XSS vulnerabilities.');
+                warnOnce(scope, SANITIZER_WARN_KEY, missingSanitizerMessage(context));
             }
             sanitized = content;
         }
@@ -659,6 +678,62 @@ export function getScrollLeft(element, rootWindow = window) {
  */ export function getMaximumScrollLeft(element) {
     return element.scrollWidth - element.clientWidth;
 }
+const OVERFLOW_TRIMMING_VALUES = [
+    'scroll',
+    'hidden',
+    'auto',
+    'clip'
+];
+const OVERFLOW_CONCRETE_VALUES = [
+    'visible',
+    'clip',
+    'hidden',
+    'scroll',
+    'auto',
+    'overlay'
+];
+/**
+ * Checks whether a single overflow axis traps the table on that axis.
+ *
+ * `overflow: clip` establishes no scroll port. When an axis is `clip` while the perpendicular axis
+ * stays `visible`, it does not trap the table's scroll — the table still scrolls with the window on
+ * the visible axis. A width-constrained, window-scrolled table sets `overflow-x: clip` on its root
+ * (see core.ts, DEV-1025); treating that root as the trimming container drops the overlays out of
+ * window-scroll mode (frozen rows stop pinning, vertical virtualization stops). Such a single-axis
+ * clip must not qualify the axis as trimming.
+ *
+ * @param {string} axis The `overflow-x`/`overflow-y` value of the axis being tested.
+ * @param {string} perpendicular The `overflow` value of the other axis.
+ * @returns {boolean}
+ */ function overflowAxisTraps(axis, perpendicular) {
+    return OVERFLOW_TRIMMING_VALUES.includes(axis) && !(axis === 'clip' && (perpendicular === 'visible' || perpendicular === ''));
+}
+/**
+ * Resolves the effective `overflow-x`/`overflow-y` of an element, preferring inline styles.
+ *
+ * The inline `overflow` shorthand can carry two values (`overflow: clip visible` → x, y). Some
+ * engines (jsdom) neither split that shorthand into `overflowX`/`overflowY` nor reflect it in the
+ * computed style, so the shorthand string is parsed directly. An inline value is only preferred when
+ * it is a concrete overflow keyword; a global keyword (`inherit`, `initial`, `revert`, `unset`) or
+ * any other non-concrete value falls back to the computed style, which resolves it to the real value
+ * (e.g. an inherited `auto`). Otherwise an inline `inherit` would be read literally and miss the
+ * scroll value it inherits.
+ *
+ * @param {HTMLElement} el The element to read overflow from.
+ * @param {CSSStyleDeclaration} computedStyle The element's computed style.
+ * @returns {{ x: string, y: string }}
+ */ function resolveOverflowAxes(el, computedStyle) {
+    const shorthand = el.style.overflow.split(/\s+/).filter(Boolean);
+    const [shorthandX = '', shorthandY = shorthandX] = shorthand;
+    const resolveAxis = (inlineAxis, shorthandAxis, computedProperty)=>{
+        const inline = inlineAxis || shorthandAxis;
+        return OVERFLOW_CONCRETE_VALUES.includes(inline) ? inline : computedStyle.getPropertyValue(computedProperty);
+    };
+    return {
+        x: resolveAxis(el.style.overflowX, shorthandX, 'overflow-x'),
+        y: resolveAxis(el.style.overflowY, shorthandY, 'overflow-y')
+    };
+}
 /**
  * Returns a DOM element responsible for trimming the provided element.
  *
@@ -669,23 +744,13 @@ export function getScrollLeft(element, rootWindow = window) {
     const rootWindow = rootDocument.defaultView;
     let el = base.parentElement;
     while(el && el.style && rootDocument.body !== el){
-        if (el.style.overflow !== 'visible' && el.style.overflow !== '') {
-            return el;
-        }
         if (rootWindow) {
-            const computedStyle = rootWindow.getComputedStyle(el);
-            const allowedProperties = [
-                'scroll',
-                'hidden',
-                'auto',
-                'clip'
-            ];
-            const property = computedStyle.getPropertyValue('overflow');
-            const propertyY = computedStyle.getPropertyValue('overflow-y');
-            const propertyX = computedStyle.getPropertyValue('overflow-x');
-            if (allowedProperties.includes(property) || allowedProperties.includes(propertyY) || allowedProperties.includes(propertyX)) {
+            const { x, y } = resolveOverflowAxes(el, rootWindow.getComputedStyle(el));
+            if (overflowAxisTraps(x, y) || overflowAxisTraps(y, x)) {
                 return el;
             }
+        } else if (el.style.overflow !== 'visible' && el.style.overflow !== '') {
+            return el;
         }
         el = el.parentElement;
     }
@@ -1027,7 +1092,7 @@ export function getScrollbarWidth(rootDocument = document) {
  *
  * @param {HTMLElement} element - DOM element.
  */ export function selectElementIfAllowed(element) {
-    const activeElement = element.ownerDocument.activeElement;
+    const activeElement = getDeepActiveElement(element.ownerDocument);
     if (isHTMLElement(activeElement) && !isOutsideInput(activeElement) && (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
         element.select();
     }
@@ -1044,8 +1109,12 @@ export function getScrollbarWidth(rootDocument = document) {
  * Set up an observer to recognize when the provided element first becomes visible and trigger a callback when it
  * happens.
  *
+ * The observer is returned so the caller can disconnect it earlier - a pending delivery carries the state from
+ * the moment its snapshot was taken, so it can arrive after the observed element (or its owner) is gone.
+ *
  * @param {HTMLElement} elementToBeObserved Element to be observed.
  * @param {Function} callback The callback function.
+ * @returns {IntersectionObserver} The observer watching the element.
  */ export function observeVisibilityChangeOnce(elementToBeObserved, callback) {
     const visibilityObserver = new IntersectionObserver((entries, observer)=>{
         entries.forEach((entry)=>{
@@ -1056,6 +1125,7 @@ export function getScrollbarWidth(rootDocument = document) {
         });
     });
     visibilityObserver.observe(elementToBeObserved);
+    return visibilityObserver;
 }
 /**
  * Add a `contenteditable` attribute, select the contents and optionally add the `invisibleSelection`
@@ -1141,10 +1211,49 @@ export function getScrollbarWidth(rootDocument = document) {
 /**
  * Check if the node is a ShadowRoot (a document fragment attached to a host element).
  *
- * @param {Node} node Node to check.
+ * @param {Node|EventTarget} node Node to check.
  * @returns {boolean} `true` if the node is a ShadowRoot.
  */ export function isShadowRoot(node) {
-    return node.nodeType === Node.DOCUMENT_FRAGMENT_NODE && 'host' in node;
+    if (typeof node !== 'object' || node === null) {
+        return false;
+    }
+    return 'nodeType' in node && node.nodeType === Node.DOCUMENT_FRAGMENT_NODE && 'host' in node;
+}
+/**
+ * Gets the chain of shadow host elements the node is rendered within, ordered from the
+ * closest host outward to the host attached to the document.
+ *
+ * @param {Node} node The node to read the host chain from.
+ * @returns {HTMLElement[]} The shadow host elements; empty when the node is not in a Shadow DOM tree.
+ */ export function getShadowHostChain(node) {
+    const hosts = [];
+    let rootNode = node.getRootNode();
+    while(isShadowRoot(rootNode)){
+        const { host } = rootNode;
+        if (!isHTMLElement(host)) {
+            break;
+        }
+        hosts.push(host);
+        rootNode = host.getRootNode();
+    }
+    return hosts;
+}
+/**
+ * Gets the deepest active (focused) element in the document. When the focus is inside
+ * a Shadow DOM tree, `document.activeElement` points at the shadow host instead of the
+ * focused element. This helper descends through the open shadow roots and returns
+ * the element that actually holds the focus.
+ *
+ * @param {Document} rootDocument The document to read the active element from.
+ * @returns {Element|null} The deepest focused element. The browser reports `document.body`
+ * when no other element holds the focus; `null` appears only in edge cases such as
+ * a document with no body.
+ */ export function getDeepActiveElement(rootDocument) {
+    let element = rootDocument.activeElement;
+    while(element?.shadowRoot?.activeElement){
+        element = element.shadowRoot.activeElement;
+    }
+    return element;
 }
 /**
  * Gets a child node at the specified index cast to the specified HTML element type.

package/helpers/dom/event.d.ts

@@ -39,6 +39,64 @@ export declare function isMiddleClick(event: Event): boolean;
  * @returns {boolean}
  */
 export declare function isTouchEvent(event: Event): boolean;
+/**
+ * One finger, as a touch event reports it.
+ */
+export interface TouchPoint {
+    identifier: number;
+    clientX: number;
+    clientY: number;
+}
+/**
+ * A DOM event that carries touch lists.
+ *
+ * `touches` is every finger currently on the screen, in the order they were placed. `changedTouches`
+ * is only the fingers this particular event is about - the ones that landed, moved, lifted or were
+ * cancelled.
+ */
+export interface TouchListEvent extends Event {
+    touches: ArrayLike<TouchPoint>;
+    changedTouches: ArrayLike<TouchPoint>;
+}
+/**
+ * Narrows a DOM event to one that carries touch lists.
+ *
+ * Detects them by property rather than with `instanceof TouchEvent`, so it also holds for an event
+ * that crossed an iframe boundary - every frame has its own `TouchEvent` constructor - and on
+ * desktop Safari, which does not expose `TouchEvent` at all. Use `isTouchEvent` when you need the
+ * stricter same-frame check instead.
+ *
+ * @param {Event} event The event object.
+ * @returns {boolean} `true` when the event carries touch lists.
+ */
+export declare function hasTouchList(event: Event): event is TouchListEvent;
+/**
+ * Reads the finger a touch event is about - the first of its `changedTouches`.
+ *
+ * Use this on `touchstart` to learn which finger began a gesture, and keep the returned
+ * `identifier` to follow that same finger through `getTouchPointById()`. Reading `touches[0]`
+ * instead would give the first finger placed *anywhere* on the screen, which is a different finger
+ * as soon as one was already resting there.
+ *
+ * @param {Event} event The event object.
+ * @returns {object|null} The finger as `{identifier, clientX, clientY}`, or `null` when the event
+ * carries no touch lists or names no changed finger.
+ */
+export declare function getFirstChangedTouch(event: Event): TouchPoint | null;
+/**
+ * Reads where one specific finger currently is.
+ *
+ * Looks the finger up in `touches`, which holds only the fingers still on the screen. A `null`
+ * result therefore answers two questions at once: where is my finger, and is it still down? That is
+ * what makes it the right test for ending a gesture on `touchend` and `touchcancel` - both fire once
+ * per finger, so "some finger lifted" is never the same question as "my finger lifted".
+ *
+ * @param {Event} event The event object.
+ * @param {number} identifier The `Touch.identifier` to look for.
+ * @returns {object|null} The finger as `{identifier, clientX, clientY}`, matching
+ * `getFirstChangedTouch()`, or `null` when it is no longer touching the screen.
+ */
+export declare function getTouchPointById(event: Event, identifier: number): TouchPoint | null;
 /**
  * Calculates the event offset until reaching the element defined by `relativeElement` argument.
  *

package/helpers/dom/event.js

@@ -9,6 +9,15 @@ function _export(target, all) {
     });
 }
 _export(exports, {
+    get getFirstChangedTouch () {
+        return getFirstChangedTouch;
+    },
+    get getTouchPointById () {
+        return getTouchPointById;
+    },
+    get hasTouchList () {
+        return hasTouchList;
+    },
     get isImmediatePropagationStopped () {
         return isImmediatePropagationStopped;
     },
@@ -51,6 +60,36 @@ function isMiddleClick(event) {
 function isTouchEvent(event) {
     return typeof TouchEvent !== 'undefined' && event instanceof TouchEvent;
 }
+function hasTouchList(event) {
+    return 'touches' in event && 'changedTouches' in event;
+}
+function getFirstChangedTouch(event) {
+    if (!hasTouchList(event) || event.changedTouches.length === 0) {
+        return null;
+    }
+    const { identifier, clientX, clientY } = event.changedTouches[0];
+    return {
+        identifier,
+        clientX,
+        clientY
+    };
+}
+function getTouchPointById(event, identifier) {
+    if (!hasTouchList(event)) {
+        return null;
+    }
+    for(let i = 0; i < event.touches.length; i++){
+        const touch = event.touches[i];
+        if (touch.identifier === identifier) {
+            return {
+                identifier: touch.identifier,
+                clientX: touch.clientX,
+                clientY: touch.clientY
+            };
+        }
+    }
+    return null;
+}
 function offsetRelativeTo(event, untilElement) {
     const offset = {
         x: event.offsetX,

package/helpers/dom/event.mjs

@@ -47,6 +47,69 @@ import { eventTargetEl, isHTMLElement } from './element.mjs';
  */ export function isTouchEvent(event) {
     return typeof TouchEvent !== 'undefined' && event instanceof TouchEvent;
 }
+/**
+ * Narrows a DOM event to one that carries touch lists.
+ *
+ * Detects them by property rather than with `instanceof TouchEvent`, so it also holds for an event
+ * that crossed an iframe boundary - every frame has its own `TouchEvent` constructor - and on
+ * desktop Safari, which does not expose `TouchEvent` at all. Use `isTouchEvent` when you need the
+ * stricter same-frame check instead.
+ *
+ * @param {Event} event The event object.
+ * @returns {boolean} `true` when the event carries touch lists.
+ */ export function hasTouchList(event) {
+    return 'touches' in event && 'changedTouches' in event;
+}
+/**
+ * Reads the finger a touch event is about - the first of its `changedTouches`.
+ *
+ * Use this on `touchstart` to learn which finger began a gesture, and keep the returned
+ * `identifier` to follow that same finger through `getTouchPointById()`. Reading `touches[0]`
+ * instead would give the first finger placed *anywhere* on the screen, which is a different finger
+ * as soon as one was already resting there.
+ *
+ * @param {Event} event The event object.
+ * @returns {object|null} The finger as `{identifier, clientX, clientY}`, or `null` when the event
+ * carries no touch lists or names no changed finger.
+ */ export function getFirstChangedTouch(event) {
+    if (!hasTouchList(event) || event.changedTouches.length === 0) {
+        return null;
+    }
+    const { identifier, clientX, clientY } = event.changedTouches[0];
+    return {
+        identifier,
+        clientX,
+        clientY
+    };
+}
+/**
+ * Reads where one specific finger currently is.
+ *
+ * Looks the finger up in `touches`, which holds only the fingers still on the screen. A `null`
+ * result therefore answers two questions at once: where is my finger, and is it still down? That is
+ * what makes it the right test for ending a gesture on `touchend` and `touchcancel` - both fire once
+ * per finger, so "some finger lifted" is never the same question as "my finger lifted".
+ *
+ * @param {Event} event The event object.
+ * @param {number} identifier The `Touch.identifier` to look for.
+ * @returns {object|null} The finger as `{identifier, clientX, clientY}`, matching
+ * `getFirstChangedTouch()`, or `null` when it is no longer touching the screen.
+ */ export function getTouchPointById(event, identifier) {
+    if (!hasTouchList(event)) {
+        return null;
+    }
+    for(let i = 0; i < event.touches.length; i++){
+        const touch = event.touches[i];
+        if (touch.identifier === identifier) {
+            return {
+                identifier: touch.identifier,
+                clientX: touch.clientX,
+                clientY: touch.clientY
+            };
+        }
+    }
+    return null;
+}
 /**
  * Calculates the event offset until reaching the element defined by `relativeElement` argument.
  *

package/helpers/errors.d.ts

@@ -4,6 +4,11 @@
  * Use this helper instead of `throw new Error()` to ensure all Handsontable errors
  * can be recognized by checking `error.cause?.handsontable === true`.
  *
+ * The cause is assigned after construction rather than passed as the `new Error(message, options)`
+ * options bag: that overload is ES2022 (Chrome 94 / Firefox 91 / Safari 15.0), above the floor
+ * declared in `../../../browser-targets.js`. Engines below it ignore the second argument silently,
+ * which would leave `error.cause` undefined and break detection with no visible failure.
+ *
  * @param message The error message to display.
  * @throws {Error} Always throws an Error with `cause: { handsontable: true }`.
  */

package/helpers/errors.js

@@ -4,6 +4,11 @@
  * Use this helper instead of `throw new Error()` to ensure all Handsontable errors
  * can be recognized by checking `error.cause?.handsontable === true`.
  *
+ * The cause is assigned after construction rather than passed as the `new Error(message, options)`
+ * options bag: that overload is ES2022 (Chrome 94 / Firefox 91 / Safari 15.0), above the floor
+ * declared in `../../../browser-targets.js`. Engines below it ignore the second argument silently,
+ * which would leave `error.cause` undefined and break detection with no visible failure.
+ *
  * @param message The error message to display.
  * @throws {Error} Always throws an Error with `cause: { handsontable: true }`.
  */ "use strict";
@@ -17,10 +22,9 @@ Object.defineProperty(exports, "throwWithCause", {
     }
 });
 function throwWithCause(message) {
-    // eslint-disable-next-line handsontable/no-native-error-throw
-    throw new Error(message, {
-        cause: {
-            handsontable: true
-        }
-    });
+    const error = new Error(message);
+    error.cause = {
+        handsontable: true
+    };
+    throw error;
 }