@slickgrid-universal/utils 4.0.2 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slickgrid-universal/utils",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Common set of small utilities",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -25,7 +25,8 @@
     "access": "public"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "/src"
   ],
   "license": "MIT",
   "author": "Ghislain B.",
@@ -43,5 +44,5 @@
     "> 1%",
     "not dead"
   ],
-  "gitHead": "bcfcd08a502c43be4a17202174f631b064b56571"
+  "gitHead": "1cfc2658f5d70e66c096e5ea77d1827dd44e0292"
 }

package/src/domUtils.ts

@@ -0,0 +1,249 @@
+import type { HtmlElementPosition, InferDOMType } from './types/index';
+
+/** calculate available space for each side of the DOM element */
+export function calculateAvailableSpace(element: HTMLElement): { top: number; bottom: number; left: number; right: number; } {
+  let bottom = 0;
+  let top = 0;
+  let left = 0;
+  let right = 0;
+
+  const windowHeight = window.innerHeight ?? 0;
+  const windowWidth = window.innerWidth ?? 0;
+  const scrollPosition = windowScrollPosition();
+  const pageScrollTop = scrollPosition.top;
+  const pageScrollLeft = scrollPosition.left;
+  const elmOffset = getOffset(element);
+
+  if (elmOffset) {
+    const elementOffsetTop = elmOffset.top ?? 0;
+    const elementOffsetLeft = elmOffset.left ?? 0;
+    top = elementOffsetTop - pageScrollTop;
+    bottom = windowHeight - (elementOffsetTop - pageScrollTop);
+    left = elementOffsetLeft - pageScrollLeft;
+    right = windowWidth - (elementOffsetLeft - pageScrollLeft);
+  }
+
+  return { top, bottom, left, right };
+}
+
+/**
+ * Create a DOM Element with any optional attributes or properties.
+ * It will only accept valid DOM element properties that `createElement` would accept.
+ * For example: `createDomElement('div', { className: 'my-css-class' })`,
+ * for style or dataset you need to use nested object `{ style: { display: 'none' }}
+ * The last argument is to optionally append the created element to a parent container element.
+ * @param {String} tagName - html tag
+ * @param {Object} options - element properties
+ * @param {[Element]} appendToParent - parent element to append to
+ */
+export function createDomElement<T extends keyof HTMLElementTagNameMap, K extends keyof HTMLElementTagNameMap[T]>(
+  tagName: T,
+  elementOptions?: null | { [P in K]: InferDOMType<HTMLElementTagNameMap[T][P]> },
+  appendToParent?: Element
+): HTMLElementTagNameMap[T] {
+  const elm = document.createElement<T>(tagName);
+
+  if (elementOptions) {
+    Object.keys(elementOptions).forEach((elmOptionKey) => {
+      if (elmOptionKey === 'innerHTML') {
+        console.warn(`[Slickgrid-Universal] For better CSP (Content Security Policy) support, do not use "innerHTML" directly in "createDomElement('${tagName}', { innerHTML: 'some html'})", ` +
+          `it is better as separate assignment: "const elm = createDomElement('span'); elm.innerHTML = 'some html';"`);
+      }
+      const elmValue = elementOptions[elmOptionKey as keyof typeof elementOptions];
+      if (typeof elmValue === 'object') {
+        Object.assign(elm[elmOptionKey as K] as object, elmValue);
+      } else {
+        elm[elmOptionKey as K] = (elementOptions as any)[elmOptionKey as keyof typeof elementOptions];
+      }
+    });
+  }
+  if (appendToParent?.appendChild) {
+    appendToParent.appendChild(elm);
+  }
+  return elm;
+}
+
+/**
+ * Loop through all properties of an object and nullify any properties that are instanceof HTMLElement,
+ * if we detect an array then use recursion to go inside it and apply same logic
+ * @param obj - object containing 1 or more properties with DOM Elements
+ */
+export function destroyAllElementProps(obj: any) {
+  if (obj) {
+    for (const key of Object.keys(obj)) {
+      if (Array.isArray(obj[key])) {
+        destroyAllElementProps(obj[key]);
+      }
+      if (obj[key] instanceof HTMLElement) {
+        obj[key] = null;
+      }
+    }
+  }
+}
+
+/**
+ * Empty a DOM element by removing all of its DOM element children leaving with an empty element (basically an empty shell)
+ * @return {object} element - updated element
+ */
+export function emptyElement<T extends Element = Element>(element?: T | null): T | undefined | null {
+  while (element?.firstChild) {
+    element.removeChild(element.firstChild);
+  }
+  return element;
+}
+
+/**
+ * From a DocumentFragment, get the innerHTML or outerHTML of all child elements.
+ * We can get the HTML by looping through all fragment `childNodes`
+ */
+export function getHTMLFromFragment(input: DocumentFragment, type: 'innerHTML' | 'outerHTML' = 'innerHTML'): string {
+  if (input instanceof DocumentFragment) {
+    return [].map.call(input.childNodes, (x: HTMLElement) => x[type]).join('') || input.textContent || '';
+  }
+  return input;
+}
+
+/** Get offset of HTML element relative to a parent element */
+export function getOffsetRelativeToParent(parentElm: HTMLElement | null, childElm: HTMLElement | null) {
+  if (!parentElm || !childElm) {
+    return undefined;
+  }
+  const parentPos = parentElm.getBoundingClientRect();
+  const childPos = childElm.getBoundingClientRect();
+  return {
+    top: childPos.top - parentPos.top,
+    right: childPos.right - parentPos.right,
+    bottom: childPos.bottom - parentPos.bottom,
+    left: childPos.left - parentPos.left,
+  };
+}
+
+/** Get HTML element offset with pure JS */
+export function getOffset(elm?: HTMLElement | null): HtmlElementPosition | undefined {
+  if (!elm || !elm.getBoundingClientRect) {
+    return undefined;
+  }
+  const box = elm.getBoundingClientRect();
+  const docElem = document.documentElement;
+
+  let top = 0;
+  let left = 0;
+  let bottom = 0;
+  let right = 0;
+
+  if (box?.top !== undefined && box.left !== undefined) {
+    top = box.top + window.pageYOffset - docElem.clientTop;
+    left = box.left + window.pageXOffset - docElem.clientLeft;
+    right = box.right;
+    bottom = box.bottom;
+  }
+  return { top, left, bottom, right };
+}
+
+export function getInnerSize(elm: HTMLElement, type: 'height' | 'width') {
+  let size = 0;
+
+  if (elm) {
+    const clientSize = type === 'height' ? 'clientHeight' : 'clientWidth';
+    const sides = type === 'height' ? ['top', 'bottom'] : ['left', 'right'];
+    size = elm[clientSize];
+    for (const side of sides) {
+      const sideSize = (parseFloat(getStyleProp(elm, `padding-${side}`) || '') || 0);
+      size -= sideSize;
+    }
+  }
+  return size;
+}
+
+/** Get a DOM element style property value by calling getComputedStyle() on the element */
+export function getStyleProp(elm: HTMLElement, property: string) {
+  if (elm) {
+    return window.getComputedStyle(elm).getPropertyValue(property);
+  }
+  return null;
+}
+
+export function findFirstAttribute(inputElm: Element | null | undefined, attributes: string[]): string | null {
+  if (inputElm) {
+    for (const attribute of attributes) {
+      const attrData = inputElm.getAttribute(attribute);
+      if (attrData) {
+        return attrData;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Provide a width as a number or a string and find associated value in valid css style format or use default value when provided (or "auto" otherwise).
+ * @param {Number|String} inputWidth - input width, could be a string or number
+ * @param {Number | String} defaultValue [defaultValue=auto] - optional default value or use "auto" when nothing is provided
+ * @returns {String} string output
+ */
+export function findWidthOrDefault(inputWidth?: number | string | null, defaultValue = 'auto'): string {
+  return (/^[0-9]+$/i.test(`${inputWidth}`) ? `${+(inputWidth as number)}px` : inputWidth as string) || defaultValue;
+}
+
+/**
+ * HTML encode using a plain <div>
+ * Create a in-memory div, set it's inner text(which a div can encode)
+ * then grab the encoded contents back out.  The div never exists on the page.
+ * @param {String} inputValue - input value to be encoded
+ * @return {String}
+ */
+export function htmlEncode(inputValue: string): string {
+  const val = typeof inputValue === 'string' ? inputValue : String(inputValue);
+  const entityMap: { [char: string]: string; } = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    '\'': '&#39;',
+  };
+  return (val || '').toString().replace(/[&<>"']/g, (s) => entityMap[s as keyof { [char: string]: string; }]);
+}
+
+/**
+ * Decode text into html entity
+ * @param string text: input text
+ * @param string text: output text
+ */
+export function htmlEntityDecode(input: string): string {
+  return input.replace(/&#(\d+);/g, (_match, dec) => {
+    return String.fromCharCode(dec);
+  });
+}
+
+/**
+ * Encode string to html special char and add html space padding defined
+ * @param {string} inputStr - input string
+ * @param {number} paddingLength - padding to add
+ */
+export function htmlEncodeWithPadding(inputStr: string, paddingLength: number): string {
+  const inputStrLn = inputStr.length;
+  let outputStr = htmlEncode(inputStr);
+
+  if (inputStrLn < paddingLength) {
+    for (let i = inputStrLn; i < paddingLength; i++) {
+      outputStr += `&nbsp;`;
+    }
+  }
+  return outputStr;
+}
+
+/** insert an HTML Element after a target Element in the DOM */
+export function insertAfterElement(referenceNode: HTMLElement, newNode: HTMLElement) {
+  referenceNode.parentNode?.insertBefore(newNode, referenceNode.nextSibling);
+}
+
+/**
+ * Get the Window Scroll top/left Position
+ * @returns
+ */
+export function windowScrollPosition(): { left: number; top: number; } {
+  return {
+    left: window.pageXOffset || document.documentElement.scrollLeft || 0,
+    top: window.pageYOffset || document.documentElement.scrollTop || 0,
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './domUtils';
+export * from './nodeExtend';
+export * from './stripTagsUtil';
+export * from './types';
+export * from './utils';

package/src/nodeExtend.ts

@@ -0,0 +1,131 @@
+/* eslint-disable guard-for-in */
+/**
+ * This extend function is a reimplementation of the npm package `extend` (also named `node-extend`).
+ * The reason for the reimplementation was mostly because the original project is not ESM compatible
+ * and written with old ES6 IIFE syntax, the goal was to reimplement and fix these old syntax and build problems.
+ * e.g. it used `var` everywhere, it used `arguments` to get function arguments, ...
+ *
+ * The previous lib can be found here at this Github link:
+ *     https://github.com/justmoon/node-extend
+ * With an MIT licence that and can be found at
+ *     https://github.com/justmoon/node-extend/blob/main/LICENSE
+ */
+
+const hasOwn = Object.prototype.hasOwnProperty;
+const toStr = Object.prototype.toString;
+const defineProperty = Object.defineProperty;
+const gOPD = Object.getOwnPropertyDescriptor;
+
+const isArray = function isArray(arr: any) {
+  if (typeof Array.isArray === 'function') {
+    return Array.isArray(arr);
+  }
+  /* istanbul ignore next */
+  return toStr.call(arr) === '[object Array]';
+};
+
+const isPlainObject = function isPlainObject(obj: any) {
+  if (!obj || toStr.call(obj) !== '[object Object]') {
+    return false;
+  }
+
+  const hasOwnConstructor = hasOwn.call(obj, 'constructor');
+  const hasIsPrototypeOf = obj.constructor && obj.constructor.prototype && hasOwn.call(obj.constructor.prototype, 'isPrototypeOf');
+  // Not own constructor property must be Object
+  if (obj.constructor && !hasOwnConstructor && !hasIsPrototypeOf) {
+    return false;
+  }
+
+  // Own properties are enumerated firstly, so to speed up, if last one is own, then all properties are own.
+  let key;
+  for (key in obj) { /**/ }
+
+  return typeof key === 'undefined' || hasOwn.call(obj, key);
+};
+
+// If name is '__proto__', and Object.defineProperty is available, define __proto__ as an own property on target
+const setProperty = function setProperty(target: any, options: any) {
+  if (defineProperty && options.name === '__proto__') {
+    defineProperty(target, options.name, {
+      enumerable: true,
+      configurable: true,
+      value: options.newValue,
+      writable: true
+    });
+  } else {
+    target[options.name] = options.newValue;
+  }
+};
+
+// Return undefined instead of __proto__ if '__proto__' is not an own property
+const getProperty = function getProperty(obj: any, name: any) {
+  if (name === '__proto__') {
+    if (!hasOwn.call(obj, name)) {
+      return void 0;
+    } else if (gOPD) {
+      // In early versions of node, obj['__proto__'] is buggy when obj has __proto__ as an own property. Object.getOwnPropertyDescriptor() works.
+      return gOPD(obj, name)!.value;
+    }
+  }
+
+  return obj[name];
+};
+
+export function extend<T = any>(...args: any[]): T {
+  let options;
+  let name;
+  let src;
+  let copy;
+  let copyIsArray;
+  let clone;
+  let target = args[0];
+  let i = 1;
+  const length = args.length;
+  let deep = false;
+
+  // Handle a deep copy situation
+  if (typeof target === 'boolean') {
+    deep = target;
+    target = args[1] || {};
+    // skip the boolean and the target
+    i = 2;
+  }
+  if (target === null || target === undefined || (typeof target !== 'object' && typeof target !== 'function')) {
+    target = {};
+  }
+
+  for (; i < length; ++i) {
+    options = args[i];
+    // Only deal with non-null/undefined values
+    if (options !== null && options !== undefined) {
+      // Extend the base object
+      for (name in options) {
+        src = getProperty(target, name);
+        copy = getProperty(options, name);
+
+        // Prevent never-ending loop
+        if (target !== copy) {
+          // Recurse if we're merging plain objects or arrays
+          if (deep && copy && (isPlainObject(copy) || (copyIsArray = isArray(copy)))) {
+            if (copyIsArray) {
+              copyIsArray = false;
+              clone = src && isArray(src) ? src : [];
+            } else {
+              clone = src && isPlainObject(src) ? src : {};
+            }
+
+            // Never move original objects, clone them
+            setProperty(target, { name, newValue: extend(deep, clone, copy) });
+
+            // Don't bring in undefined values
+          } else if (typeof copy !== 'undefined') {
+            setProperty(target, { name, newValue: copy });
+          }
+        }
+      }
+    }
+  }
+
+  // Return the modified object
+  return target;
+};

package/src/stripTagsUtil.ts

@@ -0,0 +1,193 @@
+/**
+ * This stripTags function is a lib that already existed
+ * but was not TypeScript and ESM friendly.
+ * So I ported the code into the project and removed any old code like IE11 that we don't need for our project.
+ * I also accept more input types without throwing, the code below accepts `string | number | boolean | HTMLElement` while original code only accepted string.
+ *
+ * The previous lib can be found here at this Github link:
+ *     https://github.com/ericnorris/striptags/
+ * With an MIT licence that and can be found at
+ *     https://github.com/ericnorris/striptags/blob/main/LICENSE
+ */
+
+import { isNumber } from './utils';
+
+const STATE_PLAINTEXT = Symbol('plaintext');
+const STATE_HTML = Symbol('html');
+const STATE_COMMENT = Symbol('comment');
+const ALLOWED_TAGS_REGEX = /<(\w*)>/g;
+const NORMALIZE_TAG_REGEX = /<\/?([^\s\/>]+)/;
+
+interface Context {
+  allowable_tags: Set<string | null>;
+  tag_replacement: string;
+  state: symbol;
+  tag_buffer: string;
+  depth: number;
+  in_quote_char: string;
+}
+
+export function stripTags(htmlText: string | number | boolean | HTMLElement, allowableTags?: string | string[], tagReplacement?: string) {
+
+  /** main init function that will be executed when calling the global function */
+  function init(html: string | number | boolean | HTMLElement, allowable_tags?: string | string[], tag_replacement?: string) {
+    // number/boolean should be accepted but converted to string and returned on the spot
+    // since there's no html tags to be found but we still expect a string output
+    if (typeof html !== 'string' && (isNumber(html) || typeof html === 'boolean')) {
+      return String(html);
+    }
+    if (html instanceof HTMLElement) {
+      html = html.innerHTML;
+    }
+    if (typeof html !== 'string' && html !== undefined && html !== null) {
+      throw new TypeError(`'html' parameter must be a string`);
+    }
+
+    return striptags_internal(
+      html || '',
+      init_context(allowable_tags || '', tag_replacement || '')
+    );
+  }
+
+  function init_context(allowable_tags: string | string[], tag_replacement: string): Context {
+    return {
+      allowable_tags: parse_allowable_tags(allowable_tags),
+      tag_replacement,
+      state: STATE_PLAINTEXT,
+      tag_buffer: '',
+      depth: 0,
+      in_quote_char: ''
+    };
+  }
+
+  function striptags_internal(html: string, context: Context): string {
+    const allowable_tags = context.allowable_tags;
+    const tag_replacement = context.tag_replacement;
+
+    let state = context.state;
+    let tag_buffer = context.tag_buffer;
+    let depth = context.depth;
+    let in_quote_char = context.in_quote_char;
+    let output = '';
+
+    for (let idx = 0, length = html.length; idx < length; idx++) {
+      const char = html[idx];
+
+      if (state === STATE_PLAINTEXT) {
+        switch (char) {
+          case '<':
+            state = STATE_HTML;
+            tag_buffer += char;
+            break;
+          default:
+            output += char;
+            break;
+        }
+      } else if (state === STATE_HTML) {
+        switch (char) {
+          case '<':
+            // ignore '<' if inside a quote
+            if (in_quote_char) {
+              break;
+            }
+            // we're seeing a nested '<'
+            depth++;
+            break;
+          case '>':
+            // ignore '>' if inside a quote
+            if (in_quote_char) {
+              break;
+            }
+            // something like this is happening: '<<>>'
+            if (depth) {
+              depth--;
+              break;
+            }
+            // this is closing the tag in tag_buffer
+            in_quote_char = '';
+            state = STATE_PLAINTEXT;
+            tag_buffer += '>';
+
+            if (allowable_tags.has(normalize_tag(tag_buffer))) {
+              output += tag_buffer;
+            } else {
+              output += tag_replacement;
+            }
+            tag_buffer = '';
+            break;
+          case '"':
+          case '\'':
+            // catch both single and double quotes
+            if (char === in_quote_char) {
+              in_quote_char = '';
+            } else {
+              in_quote_char = in_quote_char || char;
+            }
+            tag_buffer += char;
+            break;
+          case '-':
+            if (tag_buffer === '<!-') {
+              state = STATE_COMMENT;
+            }
+            tag_buffer += char;
+            break;
+          case ' ':
+          case '\n':
+            if (tag_buffer === '<') {
+              state = STATE_PLAINTEXT;
+              output += '< ';
+              tag_buffer = '';
+              break;
+            }
+            tag_buffer += char;
+            break;
+          default:
+            tag_buffer += char;
+            break;
+        }
+      } else if (state === STATE_COMMENT) {
+        switch (char) {
+          case '>':
+            if (tag_buffer.slice(-2) === '--') {
+              // close the comment
+              state = STATE_PLAINTEXT;
+            }
+            tag_buffer = '';
+            break;
+          default:
+            tag_buffer += char;
+            break;
+        }
+      }
+    }
+
+    // save the context for future iterations
+    context.state = state;
+    context.tag_buffer = tag_buffer;
+    context.depth = depth;
+    context.in_quote_char = in_quote_char;
+    return output;
+  }
+
+  function parse_allowable_tags(allowable_tags: string | string[]): Set<string | null> {
+    let tag_set = new Set<string>();
+
+    if (typeof allowable_tags === 'string') {
+      let match;
+      while ((match = ALLOWED_TAGS_REGEX.exec(allowable_tags))) {
+        tag_set.add(match[1]);
+      }
+    } else if (typeof allowable_tags[Symbol.iterator] === 'function') {
+      tag_set = new Set(allowable_tags);
+    }
+    return tag_set;
+  }
+
+  function normalize_tag(tag_buffer: string) {
+    const match = NORMALIZE_TAG_REGEX.exec(tag_buffer);
+    return match ? match[1].toLowerCase() : null;
+  }
+
+  // init
+  return init(htmlText, allowableTags, tagReplacement);
+}

package/src/types/htmlElementPosition.interface.ts

@@ -0,0 +1,6 @@
+export interface HtmlElementPosition {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './htmlElementPosition.interface';
+export * from './infer.type';

package/src/types/infer.type.ts

@@ -0,0 +1,6 @@
+
+/* eslint-disable @typescript-eslint/indent */
+export type InferDOMType<T> =
+  T extends CSSStyleDeclaration ? Partial<CSSStyleDeclaration> :
+  T extends infer R ? R : any;
+/* eslint-enable @typescript-eslint/indent */