handsontable 18.0.0 → 18.1.0-rc1

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;
 }

package/helpers/errors.mjs

@@ -4,13 +4,17 @@
  * 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 }`.
  */ export 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;
 }

package/helpers/feature.d.ts

@@ -11,6 +11,25 @@ export declare function requestAnimationFrame(callback: () => void): number;
  * @param {number} id The request Id, generated by `requestAnimationFrame`.
  */
 export declare function cancelAnimationFrame(id: number): void;
+/**
+ * Schedules a low-priority task to run when the browser is idle. Uses `requestIdleCallback`
+ * when available — with a timeout, so the task still progresses when the browser never idles —
+ * and falls back to `requestAnimationFrame` otherwise.
+ *
+ * Use this for background work that nothing visual waits for (e.g. cache warming); unlike an
+ * animation frame, an idle task does not compete with rendering while the user scrolls.
+ *
+ * @param {Function} callback The function to call during an idle period.
+ * @param {number} [timeout=100] The maximum delay (in milliseconds) before the task is forced to run.
+ * @returns {number}
+ */
+export declare function requestIdleTask(callback: () => void, timeout?: number): number;
+/**
+ * Cancels a task scheduled with `requestIdleTask`.
+ *
+ * @param {number} id The task Id, generated by `requestIdleTask`.
+ */
+export declare function cancelIdleTask(id: number): void;
 /**
  * @returns {boolean}
  */

package/helpers/feature.js

@@ -17,6 +17,9 @@ _export(exports, {
     get cancelAnimationFrame () {
         return cancelAnimationFrame;
     },
+    get cancelIdleTask () {
+        return cancelIdleTask;
+    },
     get getComparisonFunction () {
         return getComparisonFunction;
     },
@@ -28,6 +31,9 @@ _export(exports, {
     },
     get requestAnimationFrame () {
         return requestAnimationFrame;
+    },
+    get requestIdleTask () {
+        return requestIdleTask;
     }
 });
 function requestAnimationFrame(callback) {
@@ -36,6 +42,21 @@ function requestAnimationFrame(callback) {
 function cancelAnimationFrame(id) {
     window.cancelAnimationFrame(id);
 }
+function requestIdleTask(callback, timeout = 100) {
+    if (typeof window.requestIdleCallback === 'function') {
+        return window.requestIdleCallback(()=>callback(), {
+            timeout
+        });
+    }
+    return window.requestAnimationFrame(callback);
+}
+function cancelIdleTask(id) {
+    if (typeof window.cancelIdleCallback === 'function') {
+        window.cancelIdleCallback(id);
+    } else {
+        window.cancelAnimationFrame(id);
+    }
+}
 function isTouchSupported() {
     return 'ontouchstart' in window;
 }

package/helpers/feature.mjs

@@ -13,6 +13,36 @@
  */ export function cancelAnimationFrame(id) {
     window.cancelAnimationFrame(id);
 }
+/**
+ * Schedules a low-priority task to run when the browser is idle. Uses `requestIdleCallback`
+ * when available — with a timeout, so the task still progresses when the browser never idles —
+ * and falls back to `requestAnimationFrame` otherwise.
+ *
+ * Use this for background work that nothing visual waits for (e.g. cache warming); unlike an
+ * animation frame, an idle task does not compete with rendering while the user scrolls.
+ *
+ * @param {Function} callback The function to call during an idle period.
+ * @param {number} [timeout=100] The maximum delay (in milliseconds) before the task is forced to run.
+ * @returns {number}
+ */ export function requestIdleTask(callback, timeout = 100) {
+    if (typeof window.requestIdleCallback === 'function') {
+        return window.requestIdleCallback(()=>callback(), {
+            timeout
+        });
+    }
+    return window.requestAnimationFrame(callback);
+}
+/**
+ * Cancels a task scheduled with `requestIdleTask`.
+ *
+ * @param {number} id The task Id, generated by `requestIdleTask`.
+ */ export function cancelIdleTask(id) {
+    if (typeof window.cancelIdleCallback === 'function') {
+        window.cancelIdleCallback(id);
+    } else {
+        window.cancelAnimationFrame(id);
+    }
+}
 /**
  * @returns {boolean}
  */ export function isTouchSupported() {

package/helpers/function.d.ts

@@ -112,4 +112,4 @@ export declare function curryRight(func: (...args: unknown[]) => unknown): (...a
  * @param {*} [arg6] An argument passed to `func` function.
  * @returns {*}
  */
-export declare function fastCall(func: (...args: unknown[]) => unknown, context: unknown, arg1?: unknown, arg2?: unknown, arg3?: unknown, arg4?: unknown, arg5?: unknown, arg6?: unknown): unknown;
+export declare function fastCall(dispatchedFunc: (...args: never[]) => unknown, context: unknown, arg1?: unknown, arg2?: unknown, arg3?: unknown, arg4?: unknown, arg5?: unknown, arg6?: unknown): unknown;

package/helpers/function.js

@@ -175,7 +175,10 @@ function curryRight(func) {
     }
     return given([]);
 }
-function fastCall(func, context, arg1, arg2, arg3, arg4, arg5, arg6) {
+function fastCall(dispatchedFunc, context, arg1, arg2, arg3, arg4, arg5, arg6) {
+    // This is the designated dynamic-dispatch boundary of the hooks system: listeners are stored as
+    // the uncallable function "top type" and must be cast to a callable shape exactly here.
+    const func = dispatchedFunc;
     if ((0, _mixed.isDefined)(arg6)) {
         return func.call(context, arg1, arg2, arg3, arg4, arg5, arg6);
     } else if ((0, _mixed.isDefined)(arg5)) {

package/helpers/function.mjs

@@ -231,7 +231,10 @@ import { isDefined } from './mixed.mjs';
  * @param {*} [arg5] An argument passed to `func` function.
  * @param {*} [arg6] An argument passed to `func` function.
  * @returns {*}
- */ export function fastCall(func, context, arg1, arg2, arg3, arg4, arg5, arg6) {
+ */ export function fastCall(dispatchedFunc, context, arg1, arg2, arg3, arg4, arg5, arg6) {
+    // This is the designated dynamic-dispatch boundary of the hooks system: listeners are stored as
+    // the uncallable function "top type" and must be cast to a callable shape exactly here.
+    const func = dispatchedFunc;
     if (isDefined(arg6)) {
         return func.call(context, arg1, arg2, arg3, arg4, arg5, arg6);
     } else if (isDefined(arg5)) {

package/helpers/mixed.d.ts

@@ -1,3 +1,4 @@
+import type { LicenseLifecycle, LicenseGrants, LicenseChannels } from '../utils/entitlementLicenseKey';
 /**
  * Converts any value to string.
  *
@@ -33,9 +34,111 @@ export declare function isEmpty(variable: unknown): boolean;
  * @returns {boolean}
  */
 export declare function isRegExp(variable: unknown): boolean;
+/**
+ * Builds the "expires ..." clause of a trial message from a day count. Shared with the badge
+ * popover (`utils/licenseBranding/content.ts`), which prints the same sentence.
+ *
+ * Two counts need their own wording. `1` takes the singular unit, so the message does not read
+ * "expires in 1 days". `0` is the LAST LICENSED DAY - the named day is licensed in full - and it
+ * reads "expires today", because "expires in 0 days" describes a license that has already lapsed.
+ * The specification pins the wording for the general case only; the two edges are ours.
+ *
+ * @param {number|null|undefined} days The whole days left until the last licensed day.
+ * @returns {string}
+ */
+export declare function _formatExpiryClause(days: number | null | undefined): string;
+/**
+ * License sentences the specification repeats verbatim across surfaces - the bottom bar (here), the
+ * badge popover, and the hard-stop lock screen (`utils/licenseBranding/content.ts`). Keeping one
+ * constant per sentence means a legal or marketing wording change lands on every surface at once,
+ * instead of drifting when only one copy is updated.
+ */
+export declare const _LICENSE_EXPIRED_TITLE = "Your Handsontable license key has expired.";
+export declare const _PURCHASE_LICENSE_TEXT = "To continue using Handsontable, you need to purchase a license.";
+/**
+ * The states that render the Core-owned blocking modal (`utils/licenseBranding/lockScreen.ts`)
+ * INSTEAD of a bottom bar: a lapsed trial, a key that cannot be read, and a key that was never set.
+ * The last two spellings are shared by the legacy emitter's own state vocabulary below and by
+ * `LicenseStateKey`, so one list governs both paths.
+ *
+ * MUST list every key of `LOCK_CONTENT` (`utils/licenseBranding/content.ts`), the routing table for
+ * the modal - `licenseBranding.unit.js` asserts the two agree. `trial_hard_stop` shows no bar today
+ * only because `entitlementDomMessages` happens to have no entry for it; naming it here makes the
+ * withdrawal deliberate, so adding hard-stop bar copy later cannot put a bar underneath a
+ * non-dismissable lock. The list is NOT imported from `content.ts`: that module imports the shared
+ * copy constants from here, and the dependency must not become a cycle.
+ *
+ * The console message is unaffected - it still prints for these states. Only the bottom bar is
+ * withdrawn, because the modal now carries its sentences and two license surfaces saying the same
+ * thing at once would be noise.
+ *
+ * Frozen, and underscore-prefixed like every other license symbol here: `index.ts` copies every
+ * non-underscore export of this module onto the public `Handsontable.helper`, and a live array
+ * there could be emptied from a console to switch the blocking off at runtime.
+ *
+ * @type {readonly string[]}
+ */
+export declare const _BLOCKING_MODAL_STATES: readonly string[];
 export declare function _injectProductInfo({ className, key, element, releaseDate }: {
     className?: string;
     key?: string;
     element?: HTMLElement;
     releaseDate?: string;
 }): HTMLElement | null;
+/**
+ * Formats an epoch-millisecond timestamp as the bare "YYYY-MM-DD" UTC calendar date every license
+ * message prints. An entitlement key carries its dates as such strings already - this is only used
+ * for the one date the legacy path derives from a timestamp.
+ *
+ * @param {number} timestamp The time to format, in epoch milliseconds.
+ * @returns {string}
+ */
+export declare function _formatIsoDate(timestamp: number): string;
+/**
+ * The states outside the entitlement format: the legacy 25-character family classified the same way
+ * the frozen legacy emitter classifies it (valid, expired, missing, non-commercial), plus "invalid"
+ * (a broken legacy key, or an entitlement key that cannot be read).
+ */
+type NonEntitlementLifecycleState = 'legacy_valid' | 'legacy_expired' | 'missing' | 'non_commercial' | 'invalid';
+/**
+ * The lifecycle facet a consumer reads: the entitlement states plus the states outside the format.
+ * The entitlement-only fields fall back to `false`/`null` for the latter (except `licensedUntil`,
+ * which a legacy-expired key carries too), so a caller can read `.state` uniformly.
+ */
+export interface LicenseLifecycleFacet {
+    state: LicenseLifecycle['state'] | NonEntitlementLifecycleState;
+    isTrial: boolean;
+    daysRemaining: number | null;
+    licensedUntil: string | null;
+}
+/**
+ * Every lifecycle state a state-keyed table can hold an entry for. The console/DOM notification
+ * tables here and the badge/lock content tables in `utils/licenseBranding/content.ts` are keyed by
+ * this union rather than `string`, so the compiler rejects a typoed or unknown state key - a
+ * `string` key would compile fine and silently drop that state's entry.
+ */
+export type LicenseStateKey = LicenseLifecycleFacet['state'];
+/**
+ * The resolved license state handed to the UI and (later) the feature gates: the lifecycle facet
+ * (what the license IS right now), the channels it leaves open (where it may say so), and the
+ * grants facet (what it UNLOCKS). `grants` is never null - the same query API serves legacy keys
+ * (unlock everything) and entitlement keys (unlock what the payload lists).
+ */
+export interface LicenseStateDescriptor {
+    lifecycle: LicenseLifecycleFacet;
+    channels: LicenseChannels;
+    grants: LicenseGrants;
+}
+/**
+ * Resolves the full license state (lifecycle + channels + grants) of a license key. This is the
+ * single entry point shared by the console/DOM notification and the branding UI, so the key is
+ * classified once. A key outside the entitlement format, and an unreadable one, resolve to
+ * UNRESTRICTED grants on purpose: introducing capability gating must never take a feature away from
+ * an existing customer, and an invalid key nags - it does not strip features.
+ *
+ * @param {string} [rawKey] The license key from the grid settings, trimmed here before any classification.
+ * @param {string} [releaseDate] The build release date ("dd/mm/yyyy").
+ * @returns {LicenseStateDescriptor}
+ */
+export declare function _getLicenseState(rawKey?: string, releaseDate?: string): LicenseStateDescriptor;
+export {};