@koine/dom 1.1.5 → 1.1.6

package/getOffsetTopSlim.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Get an element's distance from the top of the Document (using more modern/performant
+ * technique compared to {@link ./getOffsetTop})
+ *
+ * @see https://stackoverflow.com/q/5598743/1938970
+ *
+ * @param elem The HTML node element
+ * @return Distance from the top in pixels
+ */
+export declare function getOffsetTopSlim(elem: HTMLElement): number;
+export default getOffsetTopSlim;

package/getOffsetTopSlim.js

@@ -0,0 +1,13 @@
+/**
+ * Get an element's distance from the top of the Document (using more modern/performant
+ * technique compared to {@link ./getOffsetTop})
+ *
+ * @see https://stackoverflow.com/q/5598743/1938970
+ *
+ * @param elem The HTML node element
+ * @return Distance from the top in pixels
+ */
+export function getOffsetTopSlim(elem) {
+    return elem.getBoundingClientRect().top + window.scrollY;
+}
+export default getOffsetTopSlim;

package/index.d.ts

@@ -12,8 +12,9 @@ export * from "./getDataAttr";
 export * from "./getDocumentHeight";
 export * from "./getHeight";
 export * from "./getListeners";
-export * from "./getOffsetTop";
 export * from "./getOffset";
+export * from "./getOffsetTop";
+export * from "./getOffsetTopSlim";
 export * from "./getScrollbarWidth";
 export * from "./getStyleValue";
 export * from "./injectCss";
@@ -24,7 +25,11 @@ export * from "./isTotallyScrolled";
 export * from "./listenLoaded";
 export * from "./listenOnce";
 export * from "./listenResize";
+export * from "./listenResizeDebounced";
+export * from "./listenResizeThrottled";
 export * from "./listenScroll";
+export * from "./listenScrollDebounced";
+export * from "./listenScrollThrottled";
 export * from "./listen";
 export * from "./off";
 export * from "./once";
@@ -37,3 +42,4 @@ export * from "./setVendorCSS";
 export * from "./siblings";
 export * from "./toArray";
 export * from "./unlisten";
+export * from "./types";

package/index.js

@@ -12,8 +12,9 @@ export * from "./getDataAttr";
 export * from "./getDocumentHeight";
 export * from "./getHeight";
 export * from "./getListeners";
-export * from "./getOffsetTop";
 export * from "./getOffset";
+export * from "./getOffsetTop";
+export * from "./getOffsetTopSlim";
 export * from "./getScrollbarWidth";
 export * from "./getStyleValue";
 export * from "./injectCss";
@@ -24,7 +25,11 @@ export * from "./isTotallyScrolled";
 export * from "./listenLoaded";
 export * from "./listenOnce";
 export * from "./listenResize";
+export * from "./listenResizeDebounced";
+export * from "./listenResizeThrottled";
 export * from "./listenScroll";
+export * from "./listenScrollDebounced";
+export * from "./listenScrollThrottled";
 export * from "./listen";
 export * from "./off";
 export * from "./once";
@@ -37,3 +42,4 @@ export * from "./setVendorCSS";
 export * from "./siblings";
 export * from "./toArray";
 export * from "./unlisten";
+export * from "./types";

package/listen.js

@@ -1,5 +1,6 @@
 import { activeEvents, eventHandler, } from "./_listen-delegation";
 import { on } from "./on";
+// import { off } from "./off";
 /**
  * Listen an event
  *

package/listenResize.d.ts

@@ -1,8 +1,8 @@
-import { debounce } from "@koine/utils";
+import type { AnyDOMEventTargetLoose } from "./types";
 /**
- * Listen window resize event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-export declare function listenResize(...args: Parameters<typeof debounce>): () => void;
+export declare const listenResize: (handler: () => void, el?: AnyDOMEventTargetLoose) => () => void;
 export default listenResize;

package/listenResize.js

@@ -1,17 +1,8 @@
-import { debounce } from "@koine/utils";
 import { on } from "./on";
 /**
- * Listen window resize event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-export function listenResize() {
-    var args = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        args[_i] = arguments[_i];
-    }
-    var handler = debounce.apply(void 0, args);
-    var unbinder = on(window, "resize", handler);
-    return unbinder;
-}
+export var listenResize = function (handler, el) { return on(el || window, "resize", handler); };
 export default listenResize;

package/listenResizeDebounced.d.ts

@@ -0,0 +1,8 @@
+import { listenResize } from "./listenResize";
+/**
+ * Listen element's (`window` by default) _resize_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export declare const listenResizeDebounced: (el?: Parameters<typeof listenResize>[1], fn: (...args: any[]) => any, wait?: number | undefined, immediate?: boolean | undefined) => () => void;
+export default listenResizeDebounced;

package/listenResizeDebounced.js

@@ -0,0 +1,41 @@
+import { debounce } from "@koine/utils";
+import { listenResize } from "./listenResize";
+/**
+ * Listen element's (`window` by default) _resize_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export var listenResizeDebounced = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return listenResize(debounce.apply(void 0, args), el);
+};
+export default listenResizeDebounced;
+// EXP: with too complex overload signature...
+// import { debounce, isUndefined } from "@koine/utils";
+// import { listenResize } from "./listenResize";
+// /**
+//  * Listen element's (`window` by default) _resize_ event debouncing the callback
+//  *
+//  * @returns An automatic unbinding function to run to deregister the listener upon call
+//  */
+// export function listenResizeDebounced(
+//   ...args: Parameters<typeof debounce>
+// ): ReturnType<typeof listenResize>;
+// export function listenResizeDebounced(
+//   el: Parameters<typeof listenResize>[1],
+//   ...args: Parameters<typeof debounce>
+// ): ReturnType<typeof listenResize>;
+// export function listenResizeDebounced(
+//   ...args:
+//     | [Parameters<typeof listenResize>[1], ...Parameters<typeof debounce>]
+//     | Parameters<typeof debounce>
+// ) {
+//   if (isUndefined(args[0])) {
+//     return listenResize(debounce(...args));
+//   }
+//   return listenResize(debounce(...args.slice(1)), args[0]);
+// }
+// export default listenResizeDebounced;

package/listenResizeThrottled.d.ts

@@ -0,0 +1,8 @@
+import { listenResize } from "./listenResize";
+/**
+ * Listen element's (`window` by default) _resize_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export declare const listenResizeThrottled: (el?: Parameters<typeof listenResize>[1], fn: Function, limit: number, context?: unknown) => () => void;
+export default listenResizeThrottled;

package/listenResizeThrottled.js

@@ -0,0 +1,15 @@
+import { throttle } from "@koine/utils";
+import { listenResize } from "./listenResize";
+/**
+ * Listen element's (`window` by default) _resize_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export var listenResizeThrottled = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return listenResize(throttle.apply(void 0, args), el);
+};
+export default listenResizeThrottled;

package/listenScroll.d.ts

@@ -1,8 +1,8 @@
-import { debounce } from "@koine/utils";
+import type { AnyDOMEventTargetLoose } from "./types";
 /**
- * Listen window scroll event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-export declare function listenScroll(...args: Parameters<typeof debounce>): () => void;
+export declare const listenScroll: (handler: () => void, el?: AnyDOMEventTargetLoose) => () => void;
 export default listenScroll;

package/listenScroll.js

@@ -1,20 +1,13 @@
-import { debounce } from "@koine/utils";
 import { on } from "./on";
 /**
- * Listen window scroll event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-export function listenScroll() {
-    var args = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        args[_i] = arguments[_i];
-    }
-    var handler = debounce.apply(void 0, args);
-    var unbinder = on(window, "scroll", handler, {
+export var listenScroll = function (handler, el) {
+    return on(el || window, "scroll", handler, {
         capture: true,
         passive: true,
     });
-    return unbinder;
-}
+};
 export default listenScroll;

package/listenScrollDebounced.d.ts

@@ -0,0 +1,8 @@
+import { listenScroll } from "./listenScroll";
+/**
+ * Listen element's (`window` by default) _scroll_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export declare const listenScrollDebounced: (el?: Parameters<typeof listenScroll>[1], fn: (...args: any[]) => any, wait?: number | undefined, immediate?: boolean | undefined) => () => void;
+export default listenScrollDebounced;

package/listenScrollDebounced.js

@@ -0,0 +1,15 @@
+import { debounce } from "@koine/utils";
+import { listenScroll } from "./listenScroll";
+/**
+ * Listen element's (`window` by default) _scroll_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export var listenScrollDebounced = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return listenScroll(debounce.apply(void 0, args), el);
+};
+export default listenScrollDebounced;

package/listenScrollThrottled.d.ts

@@ -0,0 +1,8 @@
+import { listenScroll } from "./listenScroll";
+/**
+ * Listen element's (`window` by default) _scroll_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export declare const listenScrollThrottled: (el?: Parameters<typeof listenScroll>[1], fn: Function, limit: number, context?: unknown) => () => void;
+export default listenScrollThrottled;

package/listenScrollThrottled.js

@@ -0,0 +1,15 @@
+import { throttle } from "@koine/utils";
+import { listenScroll } from "./listenScroll";
+/**
+ * Listen element's (`window` by default) _scroll_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+export var listenScrollThrottled = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return listenScroll(throttle.apply(void 0, args), el);
+};
+export default listenScrollThrottled;

package/node/getOffsetTopSlim.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOffsetTopSlim = void 0;
+/**
+ * Get an element's distance from the top of the Document (using more modern/performant
+ * technique compared to {@link ./getOffsetTop})
+ *
+ * @see https://stackoverflow.com/q/5598743/1938970
+ *
+ * @param elem The HTML node element
+ * @return Distance from the top in pixels
+ */
+function getOffsetTopSlim(elem) {
+    return elem.getBoundingClientRect().top + window.scrollY;
+}
+exports.getOffsetTopSlim = getOffsetTopSlim;
+exports.default = getOffsetTopSlim;

package/node/index.js

@@ -15,8 +15,9 @@ tslib_1.__exportStar(require("./getDataAttr"), exports);
 tslib_1.__exportStar(require("./getDocumentHeight"), exports);
 tslib_1.__exportStar(require("./getHeight"), exports);
 tslib_1.__exportStar(require("./getListeners"), exports);
-tslib_1.__exportStar(require("./getOffsetTop"), exports);
 tslib_1.__exportStar(require("./getOffset"), exports);
+tslib_1.__exportStar(require("./getOffsetTop"), exports);
+tslib_1.__exportStar(require("./getOffsetTopSlim"), exports);
 tslib_1.__exportStar(require("./getScrollbarWidth"), exports);
 tslib_1.__exportStar(require("./getStyleValue"), exports);
 tslib_1.__exportStar(require("./injectCss"), exports);
@@ -27,7 +28,11 @@ tslib_1.__exportStar(require("./isTotallyScrolled"), exports);
 tslib_1.__exportStar(require("./listenLoaded"), exports);
 tslib_1.__exportStar(require("./listenOnce"), exports);
 tslib_1.__exportStar(require("./listenResize"), exports);
+tslib_1.__exportStar(require("./listenResizeDebounced"), exports);
+tslib_1.__exportStar(require("./listenResizeThrottled"), exports);
 tslib_1.__exportStar(require("./listenScroll"), exports);
+tslib_1.__exportStar(require("./listenScrollDebounced"), exports);
+tslib_1.__exportStar(require("./listenScrollThrottled"), exports);
 tslib_1.__exportStar(require("./listen"), exports);
 tslib_1.__exportStar(require("./off"), exports);
 tslib_1.__exportStar(require("./once"), exports);
@@ -40,3 +45,4 @@ tslib_1.__exportStar(require("./setVendorCSS"), exports);
 tslib_1.__exportStar(require("./siblings"), exports);
 tslib_1.__exportStar(require("./toArray"), exports);
 tslib_1.__exportStar(require("./unlisten"), exports);
+tslib_1.__exportStar(require("./types"), exports);

package/node/listen.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.listen = void 0;
 var _listen_delegation_1 = require("./_listen-delegation");
 var on_1 = require("./on");
+// import { off } from "./off";
 /**
  * Listen an event
  *

package/node/listenResize.js

@@ -1,21 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listenResize = void 0;
-var utils_1 = require("@koine/utils");
 var on_1 = require("./on");
 /**
- * Listen window resize event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-function listenResize() {
-    var args = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        args[_i] = arguments[_i];
-    }
-    var handler = utils_1.debounce.apply(void 0, args);
-    var unbinder = (0, on_1.on)(window, "resize", handler);
-    return unbinder;
-}
+var listenResize = function (handler, el) { return (0, on_1.on)(el || window, "resize", handler); };
 exports.listenResize = listenResize;
-exports.default = listenResize;
+exports.default = exports.listenResize;

package/node/listenResizeDebounced.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenResizeDebounced = void 0;
+var utils_1 = require("@koine/utils");
+var listenResize_1 = require("./listenResize");
+/**
+ * Listen element's (`window` by default) _resize_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+var listenResizeDebounced = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return (0, listenResize_1.listenResize)(utils_1.debounce.apply(void 0, args), el);
+};
+exports.listenResizeDebounced = listenResizeDebounced;
+exports.default = exports.listenResizeDebounced;
+// EXP: with too complex overload signature...
+// import { debounce, isUndefined } from "@koine/utils";
+// import { listenResize } from "./listenResize";
+// /**
+//  * Listen element's (`window` by default) _resize_ event debouncing the callback
+//  *
+//  * @returns An automatic unbinding function to run to deregister the listener upon call
+//  */
+// export function listenResizeDebounced(
+//   ...args: Parameters<typeof debounce>
+// ): ReturnType<typeof listenResize>;
+// export function listenResizeDebounced(
+//   el: Parameters<typeof listenResize>[1],
+//   ...args: Parameters<typeof debounce>
+// ): ReturnType<typeof listenResize>;
+// export function listenResizeDebounced(
+//   ...args:
+//     | [Parameters<typeof listenResize>[1], ...Parameters<typeof debounce>]
+//     | Parameters<typeof debounce>
+// ) {
+//   if (isUndefined(args[0])) {
+//     return listenResize(debounce(...args));
+//   }
+//   return listenResize(debounce(...args.slice(1)), args[0]);
+// }
+// export default listenResizeDebounced;

package/node/listenResizeThrottled.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenResizeThrottled = void 0;
+var utils_1 = require("@koine/utils");
+var listenResize_1 = require("./listenResize");
+/**
+ * Listen element's (`window` by default) _resize_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+var listenResizeThrottled = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return (0, listenResize_1.listenResize)(utils_1.throttle.apply(void 0, args), el);
+};
+exports.listenResizeThrottled = listenResizeThrottled;
+exports.default = exports.listenResizeThrottled;

package/node/listenScroll.js

@@ -1,24 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listenScroll = void 0;
-var utils_1 = require("@koine/utils");
 var on_1 = require("./on");
 /**
- * Listen window scroll event debouncing the given handler
+ * Listen element's (`window` by default) _scroll_ event
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-function listenScroll() {
-    var args = [];
-    for (var _i = 0; _i < arguments.length; _i++) {
-        args[_i] = arguments[_i];
-    }
-    var handler = utils_1.debounce.apply(void 0, args);
-    var unbinder = (0, on_1.on)(window, "scroll", handler, {
+var listenScroll = function (handler, el) {
+    return (0, on_1.on)(el || window, "scroll", handler, {
         capture: true,
         passive: true,
     });
-    return unbinder;
-}
+};
 exports.listenScroll = listenScroll;
-exports.default = listenScroll;
+exports.default = exports.listenScroll;

package/node/listenScrollDebounced.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenScrollDebounced = void 0;
+var utils_1 = require("@koine/utils");
+var listenScroll_1 = require("./listenScroll");
+/**
+ * Listen element's (`window` by default) _scroll_ event debouncing the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+var listenScrollDebounced = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return (0, listenScroll_1.listenScroll)(utils_1.debounce.apply(void 0, args), el);
+};
+exports.listenScrollDebounced = listenScrollDebounced;
+exports.default = exports.listenScrollDebounced;

package/node/listenScrollThrottled.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenScrollThrottled = void 0;
+var utils_1 = require("@koine/utils");
+var listenScroll_1 = require("./listenScroll");
+/**
+ * Listen element's (`window` by default) _scroll_ event throttling the callback
+ *
+ * @returns An automatic unbinding function to run to deregister the listener upon call
+ */
+var listenScrollThrottled = function (el) {
+    var args = [];
+    for (var _i = 1; _i < arguments.length; _i++) {
+        args[_i - 1] = arguments[_i];
+    }
+    return (0, listenScroll_1.listenScroll)(utils_1.throttle.apply(void 0, args), el);
+};
+exports.listenScrollThrottled = listenScrollThrottled;
+exports.default = exports.listenScrollThrottled;

package/node/on.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.on = void 0;
-// import { noop } from "@koine/utils"; FIXME: build breaks with this import
 var off_1 = require("./off");
 /**
  * Shortcut for `addEventListener`

package/node/once.js

@@ -14,7 +14,7 @@ function once(el, type, handler, options) {
         handler(event);
         (0, off_1.default)(el, type, handlerWrapper);
     };
-    (0, on_1.default)(el, type, handlerWrapper, options);
+    return (0, on_1.default)(el, type, handlerWrapper, options);
 }
 exports.once = once;
 exports.default = once;

package/node/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/off.d.ts

@@ -1,5 +1,6 @@
+import type { AnyDOMEventTargetLoose } from "./types";
 /**
  * Shortcut for `removeEventListener`
  */
-export declare function off(el: Window | Document | HTMLElement | Element, type: string, handler: EventListener, options?: EventListenerOptions | boolean): void;
+export declare function off(el: AnyDOMEventTargetLoose, type: string, handler: EventListener, options?: EventListenerOptions | boolean): void;
 export default off;

package/on.d.ts

@@ -1,7 +1,8 @@
+import type { AnyDOMEventTargetLoose } from "./types";
 /**
  * Shortcut for `addEventListener`
  *
  * @returns An automatic unbinding function to run to deregister the listener upon call
  */
-export declare function on<THandler extends (event: any) => void>(el: Window | Document | HTMLElement | Element, type: string, handler: THandler, options?: AddEventListenerOptions | boolean): () => void;
+export declare function on<THandler extends (event: any) => void>(el: AnyDOMEventTargetLoose, type: string, handler: THandler, options?: AddEventListenerOptions | boolean): () => void;
 export default on;

package/on.js

@@ -1,4 +1,3 @@
-// import { noop } from "@koine/utils"; FIXME: build breaks with this import
 import { off } from "./off";
 /**
  * Shortcut for `addEventListener`

package/once.d.ts

@@ -1,6 +1,7 @@
+import { AnyDOMEventTargetLoose } from "./types";
 /**
  * One shot listener, it `addEventListener` and removes it first time is called
  * with `removeEventListener`
  */
-export declare function once(el: Window | Document | HTMLElement, type: string, handler: EventListener, options?: EventListenerOptions | boolean): void;
+export declare function once(el: AnyDOMEventTargetLoose, type: string, handler: EventListener, options?: EventListenerOptions | boolean): () => void;
 export default once;

package/once.js

@@ -10,6 +10,6 @@ export function once(el, type, handler, options) {
         handler(event);
         off(el, type, handlerWrapper);
     };
-    on(el, type, handlerWrapper, options);
+    return on(el, type, handlerWrapper, options);
 }
 export default once;

package/package.json

@@ -9,6 +9,6 @@
     "type-fest": "3.5.3",
     "tslib": "2.5.0"
   },
-  "version": "1.1.5",
+  "version": "1.1.6",
   "module": "./index.js"
 }

package/types.d.ts

@@ -0,0 +1,7 @@
+import type { AnythingFalsy } from "@koine/utils/types";
+export type AnyDOMEventTarget = Window | Document | HTMLElement | Element;
+/**
+ * We use it either throwing an error on unexisting element or falling back
+ * to `window` in case of _scroll_ or _resize_ events
+ */
+export type AnyDOMEventTargetLoose = AnyDOMEventTarget | AnythingFalsy;

package/types.js

@@ -0,0 +1 @@
+export {};