@koine/dom 2.0.0-beta.131 → 2.0.0-beta.133

package/addClass.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Add class shortcut
+ */
 export declare let addClass: <T extends Element = HTMLElement>(el?: T, className?: string) => void;
 export default addClass;

package/createElement.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Shortcut for `document.createElement`, allowing to to create an HTML element
+ * with a given className directly (a very common use case)
+ */
 export declare let createElement: <TType extends keyof HTMLElementTagNameMap | string, TElement extends HTMLElement = TType extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[TType] : HTMLElement>(type: TType, className?: string) => TElement;
 export default createElement;

package/dom.d.ts

@@ -1,2 +1,13 @@
+/**
+ * Sizzle/jQuery like DOM nodes shortcut for `document.querySelector`
+ * To avoid an extra function call we inline the above `escape`
+ *
+ * @param selector DOM selector
+ * @param parent It falls back to `window.document`
+ * @param avoidEscape Whether to avoid escaping `:` in the selector string
+ * @example <caption>Basic DOM selection</caption>
+ * const $container = dom(".my-section:");
+ * const $el = dom("[data-some-attr]", $container);
+ */
 export declare let dom: <T extends Element = HTMLElement>(selector: string, parent?: HTMLElement | Document | null, avoidEscape?: boolean) => T;
 export default dom;

package/domAll.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Sizzle/jQuery like DOM nodes shortcut for `document.querySelectorAll`
+ * To avoid an extra function call we inline the above `escape`
+ *
+ * @param string selector DOM selector
+ * @param parent It falls back to `window.document`
+ * @param avoidEscape Whether to avoid escaping `:` in the selector string
+ */
 export declare let domAll: <T extends Element = HTMLElement>(selector: string, parent?: Element | HTMLElement | Document | null, avoidEscape?: boolean) => NodeListOf<T>;
 export default domAll;

package/domEach.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Each shortcut, iterate through a NodeList of HTMLElements retrieved with the
+ * given selector (and optionally a parent container passed as thrid arguement)
+ *
+ * @param selector DOM selector
+ * @param callback
+ * @param parent It falls back to `window.document`
+ * @param scope
+ */
 export declare let domEach: <T extends Element = HTMLElement>(selector: string, callback: ($element: T, index: number) => any, parent?: HTMLElement, scope?: object) => void;
 export default domEach;

package/emitEvent.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Emit event (use only if the targeted browser supports `CustomEvent`s)
+ */
 export declare let emitEvent: (type?: string, detail?: {}) => void;
 export default emitEvent;

package/escapeSelector.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Escape colons to allow use class names as `.module:block__element`
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector#Escaping_special_characters
+ *
+ * @param selector
+ */
 export declare let escapeSelector: (selector: string) => string;
 export default escapeSelector;

package/exists.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Checks if passed node exist and is a valid element.
+ *
+ * @borrows @glidejs/glide/src/utils/dom (source)
+ */
 export declare let exists: (node?: Element) => boolean | undefined;
 export default exists;

package/forEach.d.ts

@@ -1,2 +1,7 @@
+/**
+ * For each, iterate through a `NodeList` or an `array` of `HTMLElement`s
+ *
+ * @param scope The optional `this` of the callback function
+ */
 export declare let forEach: <T extends HTMLElement, TScope = object>(nodes: NodeListOf<T> | T[], callback: (this: TScope, $element: T, index: number) => any, scope?: TScope) => void;
 export default forEach;

package/getDataAttr.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Get data attribute
+ *
+ * @param element
+ * @param attribute The name of the `data-{attr}`
+ */
 export declare let getDataAttr: (element: HTMLElement, attribute: string) => string | null;
 export default getDataAttr;

package/getDocumentHeight.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Determine the document's height
+ *
+ * @see https://github.com/cferdinandi/smooth-scroll (credits)
+ */
 export declare let getDocumentHeight: () => number;
 export default getDocumentHeight;

package/getHeight.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Get element height
+ */
 export declare let getHeight: <T extends Element>(element: T) => number;
 export default getHeight;

package/getListeners.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Get an immutable copy of all active event listeners
+ *
+ * @category listen-delegation
+ *
+ * @return Active event listeners
+ */
 export declare let getListeners: () => Partial<Record<import("./types").AnyDOMEventType, import("./_listen-delegation").ListenEvent[]>>;
 export default getListeners;

package/getOffset.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Get an element's distance from the top and left of the Document.
+ *
+ * @param elem The HTML node element
+ * @return Distance from the top and left in pixels
+ */
 export declare let getOffset: <T extends HTMLElement>(elem: T) => {
     top: number;
     left: number;

package/getOffsetTop.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Get an element's distance from the top of the Document.
+ *
+ * @see https://vanillajstoolkit.com/helpers/getoffsettop/
+ *
+ * @param elem The HTML node element
+ * @return Distance from the top in pixels
+ */
 export declare let getOffsetTop: <T extends HTMLElement>(elem: T) => number;
 export default getOffsetTop;

package/getOffsetTopSlim.d.ts

@@ -1,2 +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 let getOffsetTopSlim: <T extends HTMLElement>(elem: T) => number;
 export default getOffsetTopSlim;

package/getScrollbarWidth.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Get scrollbar's current width
+ */
 export declare let getScrollbarWidth: <T extends HTMLElement>(element?: T) => number;
 export default getScrollbarWidth;

package/getStyleValue.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Return the current style value for an element CSS property
+ *
+ * @param el The element to compute
+ * @param prop The style property
+ */
 export declare let getStyleValue: <T extends HTMLElement>(el: T, prop: string) => string;
 export default getStyleValue;

package/getVisualBackgroundColor.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Get the background color of an element eventually looking recursively into
+ * its parents, if nothing is found it returns a `#fff` background
+ */
 export declare let getVisualBackgroundColor: (elem?: null | HTMLElement) => string;
 export default getVisualBackgroundColor;

package/injectCss.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Inject css
+ *
+ * @param id The `<style>` HTMLElement's `id`
+ */
 export declare let injectCss: (id: string, cssString?: string, root?: Document) => void;
 export default injectCss;

package/isHidden.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Is element hidden?
+ */
 export declare let isHidden: <T extends HTMLElement>(el?: T) => boolean;
 export default isHidden;

package/isInViewport.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Determine if an element is in the viewport
+ *
+ * @borrows [Chris Ferdinandi](https://gomakethings.com)
+ *
+ * @param elem The element
+ * @return Returns true if element is in the viewport
+ */
 export declare let isInViewport: <T extends Element>(elem: T) => boolean;
 export default isInViewport;

package/isNodeList.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Is node list
+ *
+ * @param nodes The object to check
+ */
 export declare let isNodeList: (nodes: any) => nodes is NodeList;
 export default isNodeList;

package/isTotallyScrolled.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Is element totally scrolled
+ *
+ * @see https://github.com/willmcpo/body-scroll-lock/blob/master/src/bodyScrollLock.js#L116
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollHeight#Problems_and_solutions
+ */
 export declare let isTotallyScrolled: <T extends HTMLElement>(el?: T | null) => boolean;
 export default isTotallyScrolled;

package/listen.d.ts

@@ -1,4 +1,13 @@
 import { type EventCallback } from "./_listen-delegation";
 import type { AnyDOMEventTarget, AnyDOMEventType } from "./types";
+/**
+ * Listen an event
+ *
+ * @category listen-delegation
+ *
+ * @param types The event type or types (comma separated)
+ * @param selector The selector to run the event on
+ * @param callback The function to run when the event fires
+ */
 export declare let listen: <TTypes extends AnyDOMEventType, TTarget extends AnyDOMEventTarget = AnyDOMEventTarget>(types: TTypes, selector: string, callback: EventCallback<TTarget, TTypes>) => void;
 export default listen;

package/listenLoaded.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Fires a callback when the DOM content is loaded
+ *
+ * @see https://mathiasbynens.be/notes/settimeout-onload
+ */
 export declare let listenLoaded: (handler: (event: Event) => any) => () => void;
 export default listenLoaded;

package/listenOnce.d.ts

@@ -1,3 +1,12 @@
 import { type EventCallback } from "./_listen-delegation";
+/**
+ * Listen an event, and automatically unlisten it after it's first run
+ *
+ * @category listen-delegation
+ *
+ * @param types The event type or types (comma separated)
+ * @param selector The selector to run the event on
+ * @param callback The function to run when the event fires
+ */
 export declare let listenOnce: (types: string, selector: string, callback: EventCallback) => void;
 export default listenOnce;

package/listenResize.d.ts

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

package/listenResizeDebounced.d.ts

@@ -1,3 +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 let listenResizeDebounced: (el?: Parameters<typeof listenResize>[1], fn: (...args: any[]) => any, wait?: number | undefined, immediate?: boolean | undefined) => () => void;
 export default listenResizeDebounced;

package/listenResizeThrottled.d.ts

@@ -1,3 +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 let listenResizeThrottled: (el?: Parameters<typeof listenResize>[1], fn: Function, limit: number, context?: unknown) => () => void;
 export default listenResizeThrottled;

package/listenScroll.d.ts

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

package/listenScrollDebounced.d.ts

@@ -1,3 +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 let listenScrollDebounced: (el?: Parameters<typeof listenScroll>[1], fn: (...args: any[]) => any, wait?: number | undefined, immediate?: boolean | undefined) => () => void;
 export default listenScrollDebounced;

package/listenScrollThrottled.d.ts

@@ -1,3 +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 let listenScrollThrottled: (el?: Parameters<typeof listenScroll>[1], fn: Function, limit: number, context?: unknown) => () => void;
 export default listenScrollThrottled;

package/off.d.ts

@@ -1,3 +1,6 @@
 import type { AnyDOMEvent, AnyDOMEventTargetLoose, AnyDOMEventType } from "./types";
+/**
+ * Shortcut for `removeEventListener`
+ */
 export declare let off: <TType extends AnyDOMEventType>(el: AnyDOMEventTargetLoose, type: TType, handler: (event: AnyDOMEvent<TType>) => void, options?: EventListenerOptions | boolean) => void;
 export default off;

package/on.d.ts

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

package/once.d.ts

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

package/package.json

@@ -2,7 +2,7 @@
   "name": "@koine/dom",
   "sideEffects": false,
   "dependencies": {
-    "@koine/utils": "2.0.0-beta.131"
+    "@koine/utils": "2.0.0-beta.133"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -292,5 +292,5 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.esm.d.ts",
-  "version": "2.0.0-beta.131"
+  "version": "2.0.0-beta.133"
 }

package/removeClass.d.ts

@@ -1,2 +1,5 @@
+/**
+ * Remove class shortcut
+ */
 export declare let removeClass: <T extends Element>(el?: T, className?: string) => void;
 export default removeClass;

package/scrollTo.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Native `scrollTo`, `"smooth"` and with callback
+ *
+ * @borrows https://stackoverflow.com/a/55686711/1938970
+ *
+ * @param offset - offset to scroll to
+ * @param callback - callback function
+ * @param [fallbackTimeout] - this appears to be needed in some hard to reproduce scenario on safari, where the callback seem to be never called
+ * @param [behavior="smooth"]
+ */
 export declare let scrollTo: (destination: number, callback?: () => void, fallbackTimeout?: number, behavior?: ScrollBehavior) => void;
 export default scrollTo;

package/setDataAttr.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Set data attribute
+ *
+ * @param element
+ * @param attribute The name of the `data-{attr}`
+ * @param value The value to set, `null` or `undefined` will remove the attribute
+ */
 export declare let setDataAttr: <T extends Element>(element: T, attribute: string, value?: string | number | null | boolean) => void;
 export default setDataAttr;

package/setVendorCSS.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Set vendor CSS rule
+ *
+ * @param element A single HTMLElement
+ * @param prop CSS rule proerty
+ * @param value The CSS value to set, it will be automatically vendor prefixed
+ */
 export declare let setVendorCSS: <T extends HTMLElement>(element: T, prop: string, value: string | number | boolean) => void;
 export default setVendorCSS;

package/siblings.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Finds siblings nodes of the passed node.
+ *
+ * @borrows @glidejs/glide/src/utils/dom (source)
+ */
 export declare let siblings: <T extends Element>(node: T) => Element[];
 export default siblings;

package/toArray.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Node list to array
+ *
+ * @param nodeList
+ */
 export declare let toArray: <T extends Element>(nodeList: NodeListOf<T> | HTMLFormControlsCollection) => T[] | HTMLFormElement[];
 export default toArray;

package/types.d.ts

@@ -1,5 +1,9 @@
 import type { AnythingFalsy, LiteralUnion } from "@koine/utils";
 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;
 type StandardDOMEventTypes = keyof GlobalEventHandlersEventMap;
 export type AnyDOMEventType = LiteralUnion<StandardDOMEventTypes | "storage" | "popstate", string>;

package/unlisten.d.ts

@@ -1,4 +1,13 @@
 import { type EventCallback } from "./_listen-delegation";
 import type { AnyDOMEventTarget, AnyDOMEventType } from "./types";
+/**
+ * Stop listening for an event
+ *
+ * @category listen-delegation
+ *
+ * @param types The event type or types (comma separated)
+ * @param selector The selector to remove the event from
+ * @param callback The function to remove
+ */
 export declare let unlisten: <TTypes extends AnyDOMEventType, TTarget extends AnyDOMEventTarget = AnyDOMEventTarget>(types: TTypes, selector: string, callback: EventCallback<TTarget, TTypes>) => void;
 export default unlisten;