tool-shack 0.0.5 → 0.0.9

package/src/browser/index.ts

@@ -1,3 +1,4 @@
 export * from './isTabFocused';
+export * from './isTouchSupported';
 export * from './preferColorScheme';
 export * from './tabFocusListener';

package/src/browser/interfaces/isTouchSupported.ts

@@ -0,0 +1,3 @@
+export interface IExtendedWindow extends Window {
+  DocumentTouch: any;
+}

package/src/browser/isTabFocused.ts

@@ -1 +1,6 @@
+/**
+ * Check if current browser tab is in focus
+ *
+ * @returns Boolean indicating if current browser tab is in focus
+ */
 export const isTabFocused = (): boolean => !document.hidden;

package/src/browser/isTouchSupported.ts

@@ -0,0 +1,12 @@
+import { IExtendedWindow } from './interfaces/isTouchSupported';
+
+/**
+ * Check if user's browser supports touch events
+ *
+ * @returns Boolean indicating if user's browser support touch events
+ */
+export const isTouchSupported = (): boolean => (
+  'ontouchstart' in window || (
+    (window as unknown as IExtendedWindow).DocumentTouch && document instanceof (window as unknown as IExtendedWindow).DocumentTouch
+  )
+);

package/src/browser/preferColorScheme.ts

@@ -1,5 +1,20 @@
+/**
+ * Check if user prefers light color scheme
+ *
+ * @returns Boolean indicating if user prefers light color scheme
+ */
 export const preferLightColorScheme = (): boolean => !!(window.matchMedia('(prefers-color-scheme: light)').matches);
 
+/**
+ * Check if user prefers dark color scheme
+ *
+ * @returns Boolean indicating if user prefers dark color scheme
+ */
 export const preferDarkColorScheme = (): boolean => !!(window.matchMedia('(prefers-color-scheme: dark)').matches);
 
+/**
+ * Check what color scheme (light or dark) is prefered by user
+ *
+ * @returns String indicating prefered light color scheme ('light') or dark color scheme ('dark')
+ */
 export const preferColorScheme = (): 'light'|'dark' => preferLightColorScheme() ? 'light' : 'dark';

package/src/browser/tabFocusListener.ts

@@ -1,11 +1,18 @@
 import { isTabFocused } from './isTabFocused';
 
-export const tabFocusListener = (focusCallback: () => void, blurCallback: () => void): void => {
+/**
+ * Set callbacks for if current browser tab is in focus
+ *
+ * @param focusCallback Function to be called when current browser tab goes into focus
+ * @param blurCallback Function to be called when current browser tab goes out of focus
+ * @returns void
+ */
+export const tabFocusListener = (focusCallback?: () => void, blurCallback?: () => void): void => {
   document.addEventListener('visibilitychange', () => {
     if (isTabFocused()) {
-      focusCallback.call(this);
+      focusCallback?.call(this);
     } else {
-      blurCallback.call(this);
+      blurCallback?.call(this);
     }
   });
 }

package/src/dateTime/dateAsIso.ts

@@ -1,3 +1,9 @@
+/**
+ * Return date in ISO format with timezone
+ *
+ * @param date Date to be converted
+ * @returns ISO format with timezone
+ */
 export const dateAsIso = (date: Date) => {
   const timezoneOffset = date.getTimezoneOffset();
 

package/src/dateTime/index.ts

@@ -1,2 +1,4 @@
+export * from './interfaces';
+
 export * from './dateAsIso';
 export * from './parseDuration';

package/src/dateTime/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './parseDuration';

package/src/dateTime/interfaces/parseDuration.ts

@@ -1,7 +1,7 @@
 export interface IDuration {
-  day: number;
-  hour: number;
-  minute: number;
-  second: number;
-  millisecond: number;
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  milliseconds: number;
 }

package/src/dateTime/parseDuration.ts

@@ -1,13 +1,19 @@
 import { IDuration } from './interfaces/parseDuration';
 
+/**
+ * Parse duration in milliseconds into days, hours, minutes, seconds, milliseconds
+ *
+ * @param durationInMs Integer of duration in milliseconds
+ * @returns Object containing days, hours, minutes, seconds and milliseconds of provided duration
+ */
 export const parseDuration = (durationInMs: number): IDuration => {
   durationInMs = Math.abs(durationInMs);
 
   return {
-    day: Math.floor(durationInMs / (24 * 60 * 60 * 1000)),
-    hour: Math.floor(durationInMs / (60 * 60 * 1000)) % 24,
-    minute: Math.floor(durationInMs / (60 * 1000)) % 60,
-    second: Math.floor(durationInMs / 1000) % 60,
-    millisecond: Math.floor(durationInMs) % 1000,
+    days: Math.floor(durationInMs / (24 * 60 * 60 * 1000)),
+    hours: Math.floor(durationInMs / (60 * 60 * 1000)) % 24,
+    minutes: Math.floor(durationInMs / (60 * 1000)) % 60,
+    seconds: Math.floor(durationInMs / 1000) % 60,
+    milliseconds: Math.floor(durationInMs) % 1000,
   };
 }

package/src/dom/addAsyncEventListener.ts

@@ -1,3 +1,11 @@
+/**
+ * Listen to events fired on elements that may currently not exist in the DOM
+ *
+ * @param elementSelector Selector for element(s) to match event target
+ * @param listeners List of event types and related callback(s)
+ * @param acceptBubbling Boolean switch to allow bubbling or accept only direct element match
+ * @returns void
+ */
 export const addAsyncEventListener = (
   elementSelector: string,
   listeners: Record<string, EventListener | EventListener[]>,

package/src/dom/addClickOutsideListener.ts

@@ -0,0 +1,16 @@
+/**
+ * Add event listener to listen to clicks outside of given element
+ *
+ * @param element Node element outside which to listen to clicks
+ * @param fn Function to trigger when clicked outside
+ * @returns void
+ */
+export const addClickOutsideListener = (element: HTMLElement, fn: () => any): void => {
+  document.addEventListener('click', (event: Event) => {
+    const target = event.target as HTMLElement;
+
+    if (!!target && !element.contains(target)) {
+      fn.call(this);
+    }
+  });
+};

package/src/dom/addEventListener.ts

@@ -1,3 +1,10 @@
+/**
+ * Add event listener(s) to one or more Node elements
+ *
+ * @param element One or multiple Node element(s) to set listener(s) for
+ * @param listeners List of event types and related callback(s)
+ * @returns void
+ */
 export const addEventListener = (
   element: HTMLElement | HTMLElement[] | NodeListOf<HTMLElement> | HTMLCollectionOf<HTMLElement>,
   listeners: Record<string, EventListenerOrEventListenerObject | EventListenerOrEventListenerObject[]>

package/src/dom/appendAfter.ts

@@ -1,2 +1,9 @@
+/**
+ * Append given node after reference node in the DOM
+ *
+ * @param newNode New node element to be appended
+ * @param referenceNode Reference node element
+ * @returns Result of the action
+ */
 export const appendAfter = (newNode: HTMLElement, referenceNode: HTMLElement): boolean =>
   !!referenceNode.parentElement?.insertBefore(newNode, referenceNode.nextSibling);

package/src/dom/appendBefore.ts

@@ -1,2 +1,9 @@
+/**
+ * Append given node before reference node in the DOM
+ *
+ * @param newNode New node element to be appended
+ * @param referenceNode Reference node element
+ * @returns Result of the action
+ */
 export const appendBefore = (newNode: HTMLElement, referenceNode: HTMLElement): boolean =>
   !!referenceNode.parentElement?.insertBefore(newNode, referenceNode);

package/src/dom/createElement.ts

@@ -1,6 +1,16 @@
 import { IExtendingElementProps } from './interfaces/createElement';
 
-export const createElement = <T = HTMLElement> (tagName: string, props?: Partial<Omit<T, 'children'>> & IExtendingElementProps): T => {
+/**
+ * Method for creating Node element and assigning multiple parameters, event listeners & children in one method call
+ *
+ * @param tagName Node tag name
+ * @param props List of attributes, event listeners or/and children to assign to the newly created element
+ * @returns Resulting Node element
+ */
+export const createElement = <T = HTMLElement>(
+  tagName: string,
+  props?: Partial<Omit<T, 'children' | 'dataset'>> & IExtendingElementProps,
+): T => {
   const element: HTMLElement = document.createElement(tagName);
 
   if (props) {
@@ -18,10 +28,18 @@ export const createElement = <T = HTMLElement> (tagName: string, props?: Partial
       } else if (key === 'listeners') {
         for (let eventName in props.listeners!) {
           const functionList = (
-            props.listeners![eventName] instanceof Array ? props.listeners![eventName] : [props.listeners![eventName]]
+            props.listeners![eventName] instanceof Array
+              ? props.listeners![eventName]
+              : [props.listeners![eventName]]
           ) as EventListenerOrEventListenerObject[];
 
-          functionList.forEach((fn: EventListenerOrEventListenerObject) => element.addEventListener(eventName, fn));
+          functionList.forEach((fn: EventListenerOrEventListenerObject) =>
+            element.addEventListener(eventName, fn),
+          );
+        }
+      } else if (key === 'dataset') {
+        for (let datasetKey in props.dataset) {
+          element.dataset[datasetKey] = props.dataset[datasetKey];
         }
       } else {
         (element as any)[key] = value;

package/src/dom/fireEvent.ts

@@ -1 +1,8 @@
+/**
+ * Manually fire event on Node element
+ *
+ * @param element Node element on which should be fired event
+ * @param eventType Type name of event that should be fired
+ * @returns Result of the action
+ */
 export const fireEvent = (element: HTMLElement, eventType: string): boolean => element.dispatchEvent(new Event(eventType));

package/src/dom/index.ts

@@ -1,4 +1,7 @@
+export * from './interfaces';
+
 export * from './addAsyncEventListener';
+export * from './addClickOutsideListener';
 export * from './addEventListener';
 export * from './appendAfter';
 export * from './appendBefore';

package/src/dom/interfaces/createElement.ts

@@ -1,10 +1,35 @@
-export type TAriaLabelKey = 'atomic' | 'busy' | 'controls' | 'current' | 'describedby' | 'details' | 'disables' |
-  'dropeffect' | 'errormessage' | 'expanded' | 'flowto' | 'grabbed' | 'haspopup' | 'hidden' | 'invalid' |
-  'keyshortcuts' | 'label' | 'labelledby' | 'live' | 'modal' | 'owns' | 'relevant' | 'roledescription';
+export type TAriaLabelKey =
+  | 'atomic'
+  | 'busy'
+  | 'controls'
+  | 'current'
+  | 'describedby'
+  | 'details'
+  | 'disables'
+  | 'dropeffect'
+  | 'errormessage'
+  | 'expanded'
+  | 'flowto'
+  | 'grabbed'
+  | 'haspopup'
+  | 'hidden'
+  | 'invalid'
+  | 'keyshortcuts'
+  | 'label'
+  | 'labelledby'
+  | 'live'
+  | 'modal'
+  | 'owns'
+  | 'relevant'
+  | 'roledescription';
 
 export interface IExtendingElementProps {
   children?: HTMLElement[];
-  listeners?: Record<string, EventListenerOrEventListenerObject | EventListenerOrEventListenerObject[]>;
+  listeners?: Record<
+    string,
+    EventListenerOrEventListenerObject | EventListenerOrEventListenerObject[]
+  >;
   role?: string;
   aria?: Partial<Record<TAriaLabelKey, string>>;
+  dataset: Record<string, string>;
 }

package/src/dom/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './createElement';

package/src/general/index.ts

@@ -0,0 +1,3 @@
+export * from './isEmpty';
+export * from './isNil';
+export * from './isValidJson';

package/src/general/isEmpty.ts

@@ -0,0 +1,21 @@
+import { isNil } from './isNil';
+
+/**
+ * Check if given value is empty
+ *
+ * @param value Value to be checked
+ * @returns Boolean indicating if given value is empty
+ */
+export const isEmpty = (value: any): boolean => {
+  if (value instanceof Function) {
+    return false;
+  }
+
+  return (
+    isNil(value) ||
+    (value instanceof Object &&
+      !Object.keys(value).length &&
+      Object.getPrototypeOf(value) === Object.prototype) ||
+    !value.valueOf().toString().length
+  );
+};

package/src/general/isNil.ts

@@ -0,0 +1,7 @@
+/**
+ * Check if value is equal to null or undefined
+ *
+ * @param value Value to be checked
+ * @returns Boolean indicating if value is equal to null or undefined
+ */
+export const isNil = (value: any): boolean => value === undefined || value === null;

package/src/general/isValidJson.ts

@@ -0,0 +1,15 @@
+/**
+ * Check if string is valid JSON
+ *
+ * @param value String value to be checked
+ * @returns Boolean indicating if string value is a valid JSON
+ */
+export const isValidJson = (value: string): boolean => {
+  try {
+    JSON.parse(value);
+  } catch (error: any) {
+    return false;
+  }
+
+  return true;
+};

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './browser';
 export * from './dateTime';
 export * from './dom';
-export * from './schedule'
-export * from './string'
+export * from './general';
+export * from './schedule';
+export * from './string';

package/src/schedule/index.ts

@@ -1 +1,2 @@
+export * from './runAnimation';
 export * from './runAsync';

package/src/schedule/runAnimation.ts

@@ -0,0 +1,51 @@
+/**
+ * Run function as animation using requestAnimationFrame
+ *
+ * @param fn Function to be run as animation
+ * @param autoStart If animation should start right away or just return callbacks
+ * @returns Callbacks to start animation (startAnimation) and stop animation (stopAnimation)
+ */
+export const runAnimation = (
+  fn: () => any,
+  autoStart = true,
+): { startAnimation: () => void; stopAnimation: () => void } => {
+  let isRunning = false;
+  let requestedAnimationFrame: number | null = null;
+
+  const runAnimation = (): void => {
+    requestedAnimationFrame = requestAnimationFrame((): void => {
+      fn.call(this);
+
+      if (isRunning) {
+        runAnimation();
+      }
+    });
+  };
+
+  const startAnimation = (): void => {
+    if (isRunning) {
+      return;
+    }
+
+    isRunning = true;
+    runAnimation();
+  };
+
+  const stopAnimation = (): void => {
+    if (!isRunning) {
+      return;
+    }
+
+    isRunning = false;
+
+    if (!!requestedAnimationFrame) {
+      cancelAnimationFrame(requestedAnimationFrame);
+    }
+  };
+
+  if (autoStart) {
+    startAnimation();
+  }
+
+  return { startAnimation, stopAnimation };
+};

package/src/schedule/runAsync.ts

@@ -1,3 +1,9 @@
+/**
+ * Run function in asynchronously in Worker
+ *
+ * @param fn Function to be run asynchronously
+ * @returns Promise of expected result
+ */
 export const runAsync = <T> (fn: () => any): Promise<T> => {
   const worker = new Worker(
     URL.createObjectURL(new Blob([`postMessage((${fn})());`])),

package/src/string/escapeHTML.ts

@@ -1,3 +1,9 @@
+/**
+ * Escape special HTML related characters from string
+ *
+ * @param html String containing HTML related characters
+ * @returns Safe string with escaped HTML related characters
+ */
 export const escapeHTML = (html: string): string => {
   const tempDiv = document.createElement('div');
   tempDiv.innerText = html;

package/src/string/index.ts

@@ -1 +1,4 @@
 export * from './escapeHTML';
+export * from './removeDiacritics';
+export * from './slugify';
+export * from './truncate';

package/src/string/removeDiacritics.ts

@@ -0,0 +1,11 @@
+/**
+ * Remove diacritics & accents from string
+ *
+ * @param value String from which should be removed diacritics & accents
+ * @returns ASCII string with removed diacritics & accents
+ */
+export const removeDiacritics = (value: string): string =>
+  value
+    .normalize('NFD')
+    .toString()
+    .replace(/[\u0300-\u036f]/g, '');

package/src/string/slugify.ts

@@ -0,0 +1,17 @@
+import { removeDiacritics } from './removeDiacritics';
+
+/**
+ * Create slug from given string
+ *
+ * @param value String to be slugified
+ * @param separator One character to be used as separator (if provided longer than one character, will be automatically shortened), dash ('-') by default
+ * @returns Slugified string
+ */
+export const slugify = (value: string, separator: string = '-'): string => {
+  separator = separator.trim().substring(0, 1) || '-';
+  const removeCharsRegex = new RegExp(`[^\\\w\\\s${separator}]`, 'g');
+
+  return removeDiacritics(value.trim().toLowerCase())
+    .replace(removeCharsRegex, '')
+    .replace(/\s+/g, separator);
+};

package/src/string/truncate.ts

@@ -0,0 +1,21 @@
+/**
+ * Truncate string to maximum given length if needed and append string at the end (by default "...")
+ *
+ * @param value String value to be truncated
+ * @param maxLength Maximum allowed length
+ * @param appendedString String to append at the end, be default "..."
+ * @returns Truncated value if needed otherwise original value
+ */
+export const truncate = (
+  value: string,
+  maxLength: number,
+  appendedString: string = '...',
+): string => {
+  if (maxLength < appendedString.length) {
+    return appendedString.slice(0, maxLength);
+  }
+
+  return value.length > maxLength
+    ? value.slice(0, maxLength - appendedString.length) + appendedString
+    : value;
+};

package/tsconfig.json

@@ -13,12 +13,7 @@
     "baseUrl": ".",
     "declaration": true,
     "outDir": "./dist",
-    "lib": [
-      "dom",
-      "es2018"
-    ],
+    "lib": ["dom", "es2021"]
   },
-  "include": [
-    "src/**/*.ts"
-  ]
+  "include": ["src/**/*.ts"]
 }