@bitfiber/utils 1.0.2 → 1.0.4

package/src/common/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Represents a value, which can be undefined or null
+ */
+export type Nullish = undefined | null;
+
+/**
+ * Represents a value, which can be a number or string
+ */
+export type NumStr = number | string;
+
+/**
+ * Represents a value, which can be a number, string or symbol
+ */
+export type NumStrSym = NumStr | symbol;
+
+/**
+ * Represents any function
+ */
+export type Fn = (...args: any[]) => any;
+
+/**
+ * Represents any array
+ */
+export type Arr<T = any> = ReadonlyArray<T> | ArrayLike<T>;
+
+/**
+ * Represents all typed array types
+ */
+export type TypedArr = Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | Uint8Array
+  | Uint8ClampedArray | Uint16Array | Uint32Array | BigInt64Array | BigUint64Array;
+
+/**
+ * Represents any object
+ */
+export interface Obj<T = any> {
+  [key: NumStrSym]: T;
+}
+
+/**
+ * Represents an object with an indefinite number of string keys of type T
+ */
+export interface Index<T = any> {
+  [key: string]: T;
+}
+
+/**
+ * Represents the union of any array type and any object type
+ */
+export type ArrObj<T = any> = Arr<T> | Obj<T>;
+
+/**
+ * Converts a type union to a type intersection
+ */
+export type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I
+  : never;
+
+/**
+ * Represents the union of object value types or array value types
+ */
+export type ValueUnion<T extends ArrObj, K extends keyof T = keyof T> = T extends ReadonlyArray<any> ? T[number]
+  : T extends ArrayLike<any> ? T[number] : T extends object ? T[K] : never;
+
+/**
+ * Represents the intersection of object value types or array value types
+ */
+export type ValueIntersection<T extends ArrObj> = UnionToIntersection<ValueUnion<T>>;

package/src/dom/closest/closest.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns the same element or the closest parent element matching the selectors, otherwise null
+ * @param element - any HTML element
+ * @param selectors - target HTML element or string of valid CSS selectors
+ */
+export function closest(element: HTMLElement, selectors: string | HTMLElement): HTMLElement | null {
+  let currentElem: HTMLElement | null = element;
+
+  while (currentElem) {
+    if (selectors instanceof Element) {
+      if (currentElem === selectors) {
+        return currentElem;
+      } else {
+        currentElem = currentElem.parentElement;
+      }
+    } else if (currentElem.matches(selectors)) {
+      return currentElem;
+    } else {
+      currentElem = currentElem.parentElement;
+    }
+  }
+
+  return null;
+}

package/src/dom/document/document.ts

@@ -0,0 +1,25 @@
+import {BfError} from '../../common';
+
+let doc = typeof document === 'object' ? document : undefined;
+
+/**
+ * Returns the document object representing the HTML document in the current environment
+ */
+export function getDocument(): Document {
+  if (doc) {
+    return doc;
+  } else {
+    throw new BfError('Document is absent', {code: 'bf_utils_dom_getDocument_1'});
+  }
+}
+
+/**
+ * If the global object is not a window, you can use this function to set up a stub document implementation
+ * @example
+ * For Angular:
+ * setDocument(inject(DOCUMENT));
+ * @param document - The document object representing the HTML document in the current environment
+ */
+export function setDocument(document: Document): void {
+  doc = document;
+}

package/src/dom/download-file/download-file.ts

@@ -0,0 +1,31 @@
+import {BfError} from '../../common';
+import {getBody, getDocument, getWindow} from '../';
+
+/**
+ * Creates an offer to download a file from URL in the browser.
+ * Returns a promise that returns a blob if the download is successful
+ * @param url - file URL
+ */
+export function downloadFile(url: string): Promise<Blob> {
+  return fetch(url)
+    .then(response => {
+      if (response.ok) {
+        return response.blob();
+      } else {
+        return Promise.reject(new BfError('Network response was not ok', {code: 'bf_utils_dom_downloadFile_1'}));
+      }
+    })
+    .then(blob => {
+      const doc = getDocument();
+      const win = getWindow();
+      const body = getBody();
+      const url = win.URL.createObjectURL(blob);
+      const link = doc.createElement('a');
+      link.href = url;
+      link.download = 'downloaded_file';
+      body.appendChild(link);
+      link.click();
+      body.removeChild(link);
+      return blob;
+    });
+}

package/src/dom/for-each-elements/for-each-elements.ts

@@ -0,0 +1,17 @@
+import {forEach, INTERRUPT} from '../../common';
+
+/**
+ * Iterates through all child elements of the parent element to the full depth of the tree
+ * and calls a handler for each element.
+ * If the handler returns INTERRUPT, the loop will be interrupted
+ * @param parent - a parent element
+ * @param handler - function called for each element
+ */
+export function forEachElements(parent: Element,
+  handler: (child: Element, index: number, parent: Element) => any): void {
+  forEach(parent.children, (child, i) => {
+    if (handler(child, <number>i, parent) !== INTERRUPT) {
+      forEachElements(child, handler);
+    }
+  });
+}

package/src/dom/for-each-nodes/for-each-nodes.ts

@@ -0,0 +1,15 @@
+import {INTERRUPT} from '../../common';
+
+/**
+ * Iterates through all child nodes of the parent node to the full depth of the tree and calls a handler for each node.
+ * If the handler returns INTERRUPT, the loop will be interrupted
+ * @param parent - a parent node
+ * @param handler - function called for each node (Text, Comment, Element)
+ */
+export function forEachNodes(parent: Node, handler: (child: Node, index: number, parent: Node) => any): void {
+  parent.childNodes.forEach((child, i) => {
+    if (handler(child, i, parent) !== INTERRUPT) {
+      forEachNodes(child, handler);
+    }
+  });
+}

package/src/dom/get-all-styles/get-all-styles.ts

@@ -0,0 +1,10 @@
+import {getWindow} from '../';
+
+/**
+ * Returns all computed styles of a given HTML element
+ * @param element - any HTML element
+ */
+export function getAllStyles(element: HTMLElement): CSSStyleDeclaration {
+  const win = getWindow();
+  return win.getComputedStyle(element);
+}

package/src/dom/get-body/get-body.ts

@@ -0,0 +1,9 @@
+import {getDocument} from '../';
+
+/**
+ * Returns the <body> element of the current document
+ */
+export function getBody(): HTMLElement {
+  const doc = getDocument();
+  return doc.body;
+}

package/src/dom/get-html/get-html.ts

@@ -0,0 +1,9 @@
+import {getDocument} from '../';
+
+/**
+ *  Returns the <html> element that is the root element of the document
+ */
+export function getHtml(): HTMLElement {
+  const doc = getDocument();
+  return doc.documentElement;
+}

package/src/dom/get-non-static-parent/get-non-static-parent.ts

@@ -0,0 +1,9 @@
+import {getBody} from '../';
+
+/**
+ * Returns the closest non-static parent HTML element
+ * @param element
+ */
+export function getNonStaticParent(element: HTMLElement): HTMLElement {
+  return <HTMLElement>element.offsetParent || getBody();
+}

package/src/dom/get-offset-from-doc/get-offset-from-doc.ts

@@ -0,0 +1,18 @@
+import {getWindow, Offset} from '../';
+
+/**
+ * Returns the offset relative to the document
+ * @param element - any element
+ */
+export function getOffsetFromDoc(element: Element): Offset {
+  const win = getWindow();
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top + win.scrollY,
+    bottom: rect.bottom + win.scrollY,
+    left: rect.left + win.scrollX,
+    right: rect.right + win.scrollX,
+    width: rect.width,
+    height: rect.height,
+  };
+}

package/src/dom/get-offset-from-parent/get-offset-from-parent.ts

@@ -0,0 +1,48 @@
+import {BfError, toFloat} from '../../common';
+import {Offset, hasName, getNonStaticParent, getOffsetFromWin, getOffsetFromDoc, getStyle} from '../';
+
+/**
+ * Returns the offset relative to the closest non-static parent element.
+ * For fixed elements returns the offset relative to the global window
+ * @param element - any HTML element
+ */
+export function getOffsetFromParent(element: HTMLElement): Offset {
+  let offset: Offset;
+  let parentOffset: Offset;
+
+  if (hasName(element, 'html') || hasName(element, 'body')) {
+    throw new BfError('Element cannot be html or body', {code: 'bf_utils_dom_getOffsetFromParent_1'});
+  }
+
+  if (getStyle(element, 'position') === 'fixed') {
+    offset = getOffsetFromWin(element);
+    parentOffset = {
+      top: 0,
+      bottom: 0,
+      left: 0,
+      right: 0,
+      width: 0,
+      height: 0,
+    };
+  } else {
+    const parent = getNonStaticParent(element);
+    offset = getOffsetFromDoc(element);
+    parentOffset = getOffsetFromDoc(parent);
+
+    // The element cannot overlap its parent border, so the border width is added to the offset
+    parentOffset.top += toFloat(getStyle(parent, 'borderTopWidth'));
+    parentOffset.bottom -= toFloat(getStyle(parent, 'borderBottomWidth'));
+    parentOffset.left += toFloat(getStyle(parent, 'borderLeftWidth'));
+    parentOffset.right -= toFloat(getStyle(parent, 'borderRightWidth'));
+  }
+
+  // Subtract the element's margin so that the element is correctly placed relative to its parent
+  return {
+    top: offset.top - parentOffset.top - toFloat(getStyle(element, 'marginTop')),
+    bottom: offset.bottom - parentOffset.bottom - toFloat(getStyle(element, 'marginTop')),
+    left: offset.left - parentOffset.left - toFloat(getStyle(element, 'marginLeft')),
+    right: offset.right - parentOffset.right - toFloat(getStyle(element, 'marginLeft')),
+    width: offset.width,
+    height: offset.height,
+  };
+}

package/src/dom/get-offset-from-win/get-offset-from-win.ts

@@ -0,0 +1,9 @@
+import {Offset} from '../types';
+
+/**
+ * Returns the offset relative to the global window
+ * @param element - any element
+ */
+export function getOffsetFromWin(element: Element): Offset {
+  return element.getBoundingClientRect();
+}

package/src/dom/get-scroll-width/get-scroll-width.ts

@@ -0,0 +1,33 @@
+import {getHtml, setStyle} from '../';
+
+/**
+ * Returns width of vertical and horizontal scrollbars
+ * @param element - any HTML element, default the document's root element <html>
+ */
+export function getScrollWidth(element?: HTMLElement): {y: number; x: number} {
+  element = element || getHtml();
+  const originalValue = setStyle(element, 'overflow', 'hidden');
+  const clientWidth1 = element.clientWidth;
+  const clientHeight1 = element.clientHeight;
+
+  setStyle(element, 'overflow', 'scroll');
+  const clientWidth2 = element.clientWidth;
+  const clientHeight2 = element.clientHeight;
+
+  setStyle(element, 'overflow', originalValue);
+  let y = clientWidth1 - clientWidth2;
+  let x = clientHeight1 - clientHeight2;
+
+  if (y > 0) {
+    y += 1;
+  }
+
+  if (x > 0) {
+    x += 1;
+  }
+
+  return {
+    y,
+    x,
+  };
+}

package/src/dom/get-style/get-style.ts

@@ -0,0 +1,25 @@
+import {Index} from '../../common';
+import {getValidStyleName, getAllStyles} from '../';
+
+const validStyleValues: Index<[string, string]> = {
+  opacity: ['', '1'],
+  fontWeight: ['normal', '400'],
+  letterSpacing: ['normal', '0'],
+};
+
+/**
+ * Returns certain computed style value of a given HTML element
+ * @param element - any HTML element
+ * @param styleName - any style name
+ */
+export function getStyle(element: HTMLElement, styleName: string): string {
+  const styles = getAllStyles(element);
+  const validName = getValidStyleName(styleName);
+  const value = styles.getPropertyValue(validName);
+
+  if (validStyleValues[validName] && value === validStyleValues[validName][0]) {
+    return validStyleValues[validName][1];
+  } else {
+    return value;
+  }
+}

package/src/dom/get-styles/get-styles.ts

@@ -0,0 +1,14 @@
+import {ValueUnion} from '../../common';
+import {getStyle} from '../';
+
+/**
+ * Returns an object with the specified computed styles for a given HTML element
+ * @param element - any HTML element
+ * @param styleNames - list of certain style names
+ */
+export function getStyles<A extends string[]>(element: HTMLElement,
+  ...styleNames: A): {[K in ValueUnion<A>]: string} {
+  const styles: {[K in ValueUnion<A>]: string} = <any>{};
+  styleNames.forEach(name => (<any>styles)[name] = getStyle(element, name));
+  return styles;
+}

package/src/dom/get-valid-style-name/get-valid-style-name.ts

@@ -0,0 +1,45 @@
+import {BfError, Index} from '../../common';
+import {withCapital, toCamelCase} from '../../str';
+import {getDocument} from '../';
+
+let defaultStyles: CSSStyleDeclaration;
+const vendorPrefixes = ['Webkit', 'Moz'];
+const validStyleNames: Index<string> = {float: 'cssFloat'};
+
+/**
+ * Attempts to convert the name to a valid style name.
+ * Returns a valid style name or throws an exception if a valid name is not found
+ * @param name - any name
+ */
+export function getValidStyleName(name: string): string {
+  if (!defaultStyles) {
+    const doc = getDocument();
+    defaultStyles = doc.createElement('div').style;
+  }
+
+  if (name in validStyleNames) {
+    return validStyleNames[name];
+  } else {
+    const camelName = toCamelCase(name);
+
+    if (camelName in defaultStyles) {
+      validStyleNames[name] = camelName;
+    } else {
+      const baseName = withCapital(camelName);
+
+      for (const prefix of vendorPrefixes) {
+        const fullName = prefix + baseName;
+        if (fullName in defaultStyles) {
+          validStyleNames[name] = fullName;
+          break;
+        }
+      }
+
+      if (!(name in validStyleNames)) {
+        throw new BfError('Incorrect style name', {code: 'bf_utils_dom_getValidStyleName_1'});
+      }
+    }
+
+    return validStyleNames[name];
+  }
+}

package/src/dom/get-window/get-window.ts

@@ -0,0 +1,17 @@
+import {BfError} from '../../common';
+import {getDocument} from '../';
+
+let win = typeof window === 'object' ? window : undefined;
+
+/**
+ * Returns the global window object in the current environment
+ */
+export function getWindow(): Window & typeof globalThis {
+  const doc = getDocument();
+  win = doc.defaultView || win;
+  if (win) {
+    return win;
+  } else {
+    throw new BfError('Window is absent', {code: 'bf_utils_dom_getWindow_1'});
+  }
+}

package/src/dom/has-name/has-name.ts

@@ -0,0 +1,8 @@
+/**
+ * Determines if the name of the passed element matches a specific name
+ * @param element - any HTML element
+ * @param name - any node name
+ */
+export function hasName(element: Element, name: string): boolean {
+  return element.nodeName.toLowerCase() === name.toLowerCase();
+}

package/src/dom/index.ts

@@ -0,0 +1,25 @@
+export {TopLeft, Offset} from './types';
+export {isText} from './is-text/is-text';
+export {isComment} from './is-comment/is-comment';
+export {isElement} from './is-element/is-element';
+export {hasName} from './has-name/has-name';
+export {getDocument, setDocument} from './document/document';
+export {getWindow} from './get-window/get-window';
+export {getHtml} from './get-html/get-html';
+export {getBody} from './get-body/get-body';
+export {closest} from './closest/closest';
+export {getNonStaticParent} from './get-non-static-parent/get-non-static-parent';
+export {getOffsetFromWin} from './get-offset-from-win/get-offset-from-win';
+export {getOffsetFromDoc} from './get-offset-from-doc/get-offset-from-doc';
+export {getOffsetFromParent} from './get-offset-from-parent/get-offset-from-parent';
+export {setOffsetFromParent} from './set-offset-from-parent/set-offset-from-parent';
+export {getValidStyleName} from './get-valid-style-name/get-valid-style-name';
+export {getScrollWidth} from './get-scroll-width/get-scroll-width';
+export {downloadFile} from './download-file/download-file';
+export {forEachNodes} from './for-each-nodes/for-each-nodes';
+export {forEachElements} from './for-each-elements/for-each-elements';
+export {getAllStyles} from './get-all-styles/get-all-styles';
+export {getStyle} from './get-style/get-style';
+export {getStyles} from './get-styles/get-styles';
+export {setStyle} from './set-style/set-style';
+export {setStyles} from './set-styles/set-styles';

package/src/dom/is-comment/is-comment.ts

@@ -0,0 +1,7 @@
+/**
+ * Determines if the given node represents a comment
+ * @param value - any value
+ */
+export function isComment(value: any): value is Comment {
+  return value instanceof Comment;
+}

package/src/dom/is-element/is-element.ts

@@ -0,0 +1,7 @@
+/**
+ * Determines if the given node represents an element
+ * @param value - any value
+ */
+export function isElement(value: any): value is Element {
+  return value instanceof Element;
+}

package/src/dom/is-text/is-text.ts

@@ -0,0 +1,7 @@
+/**
+ * Determines if the given node represents a text node
+ * @param value - any value
+ */
+export function isText(value: any): value is Text {
+  return value instanceof Text;
+}

package/src/dom/set-offset-from-parent/set-offset-from-parent.ts

@@ -0,0 +1,46 @@
+import {isNumber, toFloat} from '../../common';
+import {TopLeft, getOffsetFromParent, setStyle, getStyle, setStyles} from '../';
+
+/**
+ * Sets the offset relative to the closest non-static parent element
+ * For fixed elements sets the offset relative to the global window
+ * @param element - any HTML element
+ * @param offset - top and left position relative to the parent HTML element
+ */
+export function setOffsetFromParent(element: HTMLElement, offset: Partial<TopLeft>): void {
+  let top = 0;
+  let left = 0;
+  let styleTop = getStyle(element, 'top');
+  let styleLeft = getStyle(element, 'left');
+  const position = getStyle(element, 'position');
+  const styles: {top?: string; left?: string} = {};
+
+  // An element cannot be static for offset applying
+  if (position === 'static') {
+    styleTop = '0'; // because top was ignored for a static element
+    styleLeft = '0'; // because left was ignored for a static element
+    setStyle(element, 'position', 'relative');
+  }
+
+  // If top or left is auto, need calculate real top and left relative to a non-static parent
+  if ((position === 'absolute' || position === 'fixed') && (styleTop === 'auto' || styleLeft === 'auto')) {
+    const offsetFromParent = getOffsetFromParent(element);
+    top = offsetFromParent.top;
+    left = offsetFromParent.left;
+  } else {
+    top = toFloat(styleTop);
+    left = toFloat(styleLeft);
+  }
+
+  if (isNumber(offset.top)) {
+    const newTop = top + offset.top;
+    styles.top = newTop !== 0 ? newTop + 'px' : '0';
+  }
+
+  if (isNumber(offset.left)) {
+    const newLeft = left + offset.left;
+    styles.left = newLeft !== 0 ? newLeft + 'px' : '0';
+  }
+
+  setStyles(element, styles);
+}

package/src/dom/set-style/set-style.ts

@@ -0,0 +1,14 @@
+import {getStyle} from '../';
+
+/**
+ * Sets a new value for a certain style for a given HTML element
+ * @param element - any HTML element
+ * @param styleName - any style name
+ * @param value - new value for style
+ * @returns previous value for style
+ */
+export function setStyle(element: HTMLElement, styleName: string, value: string): string {
+  const originalStyle = getStyle(element, styleName);
+  (<any>element.style)[styleName] = value;
+  return originalStyle;
+}

package/src/dom/set-styles/set-styles.ts

@@ -0,0 +1,17 @@
+import {Index} from '../../common';
+import {forEachObj} from '../../obj';
+import {setStyle} from '../';
+
+/**
+ * Sets new styles for a given HTML element
+ * @param element - any HTML element
+ * @param styles - object containing new styles
+ * @returns object containing previous styles
+ */
+export function setStyles<T extends Index<string>>(element: HTMLElement, styles: T): T {
+  const originalStyles = <T>{};
+  forEachObj(styles, (value, key) => {
+    (<any>originalStyles)[key] = setStyle(element, <string>key, value);
+  });
+  return originalStyles;
+}

package/src/dom/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Represents an object with two properties top and left
+ */
+export interface TopLeft {
+  top: number;
+  left: number;
+}
+
+/**
+ * Represents the response type for the following functions:
+ * getOffsetFromWin, getOffsetFromDoc and getOffsetFromParent
+ */
+export interface Offset {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+  width: number;
+  height: number;
+}

package/src/env/get-browser/get-browser.ts

@@ -0,0 +1,38 @@
+import {BrowserData} from '../';
+import {EnvCondition} from '../types';
+import {getBot, getEnvData} from '../private/private';
+
+let browser: BrowserData | null = null;
+
+const browserConditions: EnvCondition[] = [
+  ['opera', '(?:opera|opr\\/|opios)'], ['operaCoast', 'coast\\/'], ['operaTouch', 'opt\\/'],
+  ['samsung', 'SamsungBrowser'], ['mz', 'MZBrowser'], ['yandex', 'YaBrowser'], ['uc', 'UcBrowser'],
+  ['maxthon', '(?:Maxthon|mxios)'], ['kmeleon', 'k-meleon'], ['wechat', 'MicroMessenger'], ['qqLite', 'qqBrowserLite'],
+  ['qq', 'qqBrowser'], ['edge', 'edg(?:[ea/]|ios)'], ['sailfish', 'sailfish\\s?(?:browser)?'],
+  ['webOS', 'w(?:eb)?[o0]sbrowser'], ['tizen', 'tizen\\s?(?:browser)?'], ['miui', 'MiuiBrowser'], 'silk', 'phantomjs',
+  'slimerjs', 'qupzilla', 'electron', 'whale', 'focus', 'swing', 'epiphany', 'puffin', 'sleipnir', 'vivaldi',
+  'seamonkey', ['playstation4', 'playstation 4'], ['playstation5', 'playstation 5'], ['googleSearch', 'GSA'],
+  ['firefox', '(?:firefox|FxiOS)'], ['chrome', '(?:chrome|chromium|crios|crmo)'], 'android',
+  ['safari', '(?:safari|AppleWebKit)'],
+];
+
+/**
+ * Returns information about the browser.
+ * Possible browser names: opera | operaCoast | operaTouch | samsung | mz | yandex | uc | maxthon | kmeleon
+ * | wechat | qqLite | qq | edge | sailfish | webOS | tizen | miui | silk | phantomjs | slimerjs | qupzilla
+ * | electron | whale | focus | swing | epiphany | puffin | sleipnir | vivaldi | seamonkey | playstation4
+ * | playstation5 | googleSearch | firefox | chrome | android | safari | unknown | BotNames
+ */
+export function getBrowser(): BrowserData {
+  const bot = getBot();
+  browser ??= bot.name !== 'unknown' ? {...bot} : <BrowserData>getEnvData(browserConditions, true);
+  return <BrowserData>browser;
+}
+
+/*
+ * @internal
+ * For internal use
+ */
+export function resetBrowser(): void {
+  browser = null;
+}