@24i/bigscreen-sdk 0.9.9-alpha.2147 → 0.9.9-alpha.2149

package/packages/utils/README.md

@@ -0,0 +1,336 @@
+---
+id: README
+title: Utils
+hide_title: true
+sidebar_label: Utils
+---
+
+# Utils
+This package is a set of tools that do not fit to any other package.
+
+You can either import all utils if you use it like this:
+```ts
+import { generateUuid } from '@24i/bigscreen-sdk/utils';
+```
+Or you can import single functions like this:
+```ts
+import { generateUuid } from '@24i/bigscreen-sdk/utils/generateUuid';
+```
+
+## Available utils
+- **[addClass](#addClass)** - safely adds class to reference.
+- **[debounce](#debounce)** - debounced function is only executed again after a period of not being called, supports leading, trailing (default) and both executions.
+- **[displayToggler](#displayToggler)** - exports `getDisplayToggler` that allows you to easily show/hide an element with guard preventing unnecessary DOM calls.
+- **[generateUuid](#generateUuid)** - function to get UUIDv4 according to RFC 4122.
+- **[isMouseUsed](#isMouseUsed)** - **DEPRECATED** moved to `device` package.
+- **[memoryInfo](#memoryInfo)** - two functions that returns currently active segment size and total allocated size of JS heap, in bytes.
+- **[noop](#noop)** - for all your noop needs, keep only 1 reference.
+- **[nTimes](#nTimes)** - for generating n of something (e.g. 4 same elements).
+- **[offsetPosition](#offsetPosition)** - safely sets references transform to translate x/y, uses top/left if transform not supported, allows for forcing top/left or transform mode.
+- **[removeClass](#removeClass)** - safely removes class from reference.
+- **[scaledImage](#scaledImage)** - returns URL for scaledImage.
+- **[stopEvent](#stopEvent)** - calls stopPropagation and preventDefault on provided event.
+- **[timeConstants](#timeConstants)** - exports frequently used time constants.
+- **[timers](#timers)** - functions to simplify work with setTimeout and setInterval.
+- **[counter](#counter)** - exports `createCounter` that allows you to add value to counter till callback is triggered at some point.
+- **[xhr](#xhr)** - provides wrap over `XMLHttpRequest`, with the possibility to repeat the failing request.
+
+### addClass
+Adds a class to the element in the reference.
+
+It takes two params:
+- `element: Reference<HTMLElement>` - ref to element to which to add the class
+- `class: string` - class to add
+
+### debounce
+Debounces the function to prevent too frequent calls.
+
+It takes 2 mandatory and 1 optional param:
+- `func: Function` - function to debounce
+- `debounceTime: number` - time of debounce in ms
+- `{ leading?, trailing? }?: DebounceConfig = { trailing: true }` - setting whether to call on leading or trailing edge
+**Usage**
+```ts
+showVertical = debounce((model: Program) => {
+    // implementation
+}, this.props.verticalDebounceTime);
+
+showHorizontal = debounce((model: Program) => {
+    // implementation
+}, this.props.horizontalDebounceTime);
+
+show(model: Program) {
+    const isVertical = // some condition
+    this.activeDebounce?.cancel();
+    this.activeDebounce = isVertical ? this.showVertical(model) : this.showHorizontal(model);
+}
+```
+
+### displayToggler
+Unifies showing and hiding an element. Has guard to prevent multiple unnecessary DOM calls.
+It is important to correctly set the `initialIsHidden` value and not to change the display class in other ways.
+You can keep calling show/hide multiple times in a row. Classlist will be accessed and edited only once.
+It imports the needed styles for you so you do not need to take care of that in the project.
+```scss
+.display-none {
+    display: none;
+}
+```
+
+It exports 3 values:
+- `DISPLAY_NONE` - string `display-none` (class name)
+- `getDisplayToggler` - setup function with element and initial shown/hide value
+- `IDisplayToggler` - interface returned by `getDisplayToggler`
+
+`getDisplayToggler` takes 1 mandatory and 1 optional param:
+- `element: Reference<HTMLElement>` - element that will be shown/hidden
+- `initialIsHidden?: boolean = false` - initial state of hidden value
+
+And returns `IDisplayToggler` interface with 4 functions:
+- `show: () => void;` - removes `display-none` class
+- `hide: () => void;` - adds `display-none` class
+- `isVisible: () => boolean;` - returns true if the element is visible, false otherwise
+- `isHidden: () => boolean;` - returns true if the element is hidden, false otherwise
+
+### generateUuid
+Returns an UUIDv4 according to RFC 4122, like ex. "123e4567-e89b-12d3-a456-426614174000".
+
+### isMouseUsed
+**DEPRECATED** moved to `device` package.
+
+### memoryInfo
+It exports 2 function:
+- `getUsedJSHeapSize: () => number;` - The currently active segment of JS heap, in bytes.
+- `getTotalJSHeapSize: () => number;` -  The total allocated heap size, in bytes.
+
+### noop
+No operation function for your needs.
+
+### nTimes
+Maps an array of n empty elements to another array. E.g.:
+```tsx
+const MAX_DIGITS = 5;
+
+<div className="numeri-zapper">
+    {nTimes(MAX_DIGITS, () => <div className="zapper-number">-</div>)}
+</div>
+```
+
+### offsetPosition
+Function to change the position of the element in x, y fashion.
+It automatically uses `transform` if available and if not disabled by the application.
+It also takes into account the language direction and
+automatically flips the x offset for right-to-left cases.
+
+It takes 2 mandatory params and 1 optional:
+- `element: Reference<HTMLElement>` - element which position will be changed
+- `offset: { x?: number | string, y?: number | string }` - position offset
+You can pass either number or `${number}px` to offset and you can set only one of x, y or both.
+- `rtl: boolean = isRtl()` - boolean flag setting text direction defaulting to used language.
+
+It also has 3 namespaced functions for your control:
+- `offsetPosition.usesTransform() => boolean` - returns true if transform is used
+- `offsetPosition.forceTransform() => void` - enforces the use of transform
+- `offsetPosition.forceTopLeft() => void` - enforces the use of top/left properties
+
+### removeClass
+Removes a class from the element in the reference.
+
+It takes 2 params:
+- `element: Reference<HTMLElement>` - ref to element from which to remove the class
+- `class: string` - class to remove
+
+### scaledImage
+Returns the URL for scaled image
+
+It takes 2 required params and 1 optional:
+- `url: string` - the URL of image to scale
+- `dimensions: { height: number; width: number, fit?: 'cover' | 'contain' | 'inside' }` -
+the dimensions of the resulting image, `fit` defaults to `'cover'`
+- `scalingServer` - optional base url of scaling server (defaults to `http://imageresize.24i.com`)
+
+Fit option:
+- `cover` - similar to CSS cover it crops the image to fully cover required area with image data
+- `contain` - it fits the image inside the required frame and then adds transparent areas to fill
+the required size
+- `inside` - it fits the image inside the required frame and returns smaller image. (It does not add
+the transparent sides like `contain` does.)
+
+### stopEvent
+Calls `preventDefault` and `stopPropagation`
+
+It takes 1 param:
+- `event: Event` - event to stop
+
+If you need to stop event immediately, there is also an export `stopEventImmediately` that calls
+`stopImmediatePropagation` as well.
+
+### timeConstants
+```ts
+export const SECONDS_PER_MINUTE = 60;
+export const MINUTES_PER_HALF_HOUR = 30;
+export const MINUTES_PER_HOUR = 60;
+export const HOURS_PER_DAY = 24;
+export const DAYS_PER_WEEK = 7;
+export const SECOND_IN_MS = 1000;
+export const MINUTE_IN_MS = SECOND_IN_MS * SECONDS_PER_MINUTE;
+export const HALF_HOUR_IN_MS = MINUTE_IN_MS * MINUTES_PER_HALF_HOUR;
+export const HOUR_IN_MS = MINUTE_IN_MS * MINUTES_PER_HOUR;
+export const DAY_IN_MS = HOUR_IN_MS * HOURS_PER_DAY;
+```
+
+### timers
+Timers exports three functions: `createTimeout`, `createInterval` and `runAsync`.
+
+#### createTimeout and createInterval
+`createTimeout` and `createInterval` differ only in calling either set/clearTimeout or set/clearInterval.
+Therefore only one is needed to be described. The idea behind these functions is to remove the need
+to handle the work with timeout/interval id in the code by yourself.
+
+They both return the same interface (also exported):
+```ts
+interface TimedFunction {
+    /**
+     * Function to set timeout or interval the same way you would setTimeout or setInterval
+     * @param callbackFn function to call on timeout or every interval
+     * @param timeMs timeout in ms or interval length in ms
+     */
+    set: (callbackFn: () => void, timeMs: number) => void,
+    /**
+     * Function to cancel the timeout or interval
+     */
+    clear: () => void,
+    /**
+     * Function that returns true if the timeout or interval is active.
+     * Timeout: was not yet run && was not cancel (in other words is pending)
+     * Interval: waiting for next run (in other words was set and not cleared)
+     */
+    isActive: () => boolean,
+}
+```
+
+Usual example how you would do it without these utils:
+```ts
+class MyComponent extends Component<Props> {
+    updateIntervalId: number | null = null;
+
+    componentDidMount() {
+        this.updateIntervalId = window.setInterval(this.onInterval, UPDATE_INTERVAL_TIME);
+    }
+
+    componentWillUnmount() {
+        if (this.updateIntervalId !== null) {
+            window.clearInterval(this.updateIntervalId);
+            this.updateIntervalId = null;
+        }
+    }
+}
+```
+now with `createInterval`:
+```ts
+class MyComponent extends Component<Props> {
+    updateInterval = createInterval();
+
+    componentDidMount() {
+        this.updateInterval.set(this.onInterval, UPDATE_INTERVAL_TIME);
+    }
+
+    componentWillUnmount() {
+        this.updateInterval.clear();
+    }
+}
+```
+Sometimes you also extend the timeout before it runs little bit like this:
+```ts
+if (this.debounceTimeoutId) {
+    window.clearTimeout(this.debounceTimeoutId);
+}
+this.debounceTimeoutId = window.setTimeout(this.debouncedFn, DEBOUNCE_TIME);
+```
+with `createTimeout` you can shorten this to:
+```ts
+this.debounceTimeout.set(this.debouncedFn, DEBOUNCE_TIME);
+```
+The clearing of the previous timeout is done for you. The same applies to `createInterval`.
+
+#### runAsync
+
+`runAsync` is just a tiny utility to make code more readable. From time to time, we need to run part
+of the code to run async from the rest. Usually, we do it like this:
+```ts
+window.setTimeout(() => {
+    // code that runs async
+}, 0);
+```
+with `runAsync` we can write it like this:
+```ts
+runAsync(() => {
+    // code that runs async
+});
+```
+The advantage is a clear code that tells you nicely what it does (plus it is slightly shorter).
+
+### counter
+Unify simple functionality of triggering callback after certain value is on or above limit. For example, you need to
+trigger callback after 3 iterations increased by number 1, so you will create counter like this:
+
+```ts
+const counter = createCounter({
+    triggerAt: 3,
+    callback: () => { console.log('All systems nominal') }
+});
+
+counter.add(); // increase counter by default number 1
+counter.add();
+counter.add();
+// All systems nominal
+
+counter.reset();
+counter.add(3); // increase counter by custom number 3
+// All systems nominal
+```
+
+### xhr
+Provides wrap over `XMLHttpRequest`, with the possibility to repeat the failing request.
+Exports two methods: `xhrSend` and `xhrSendRetry`.
+
+#### xhrSend
+Wrap over `XMLHttpRequest`, without the possibility to repeat the failing request.
+
+```ts
+const url = 'http://test.com';
+const options = {
+    method: 'POST',
+    headers: {
+        headerA: 'headerValueA',
+    },
+    body: 'payload data',
+};
+const response = await xhrSend(url, options);
+```
+
+#### xhrSendRetry
+Wraps `xhrSend` function to allow retrying the failing request X times.
+
+```ts
+const url = 'http://test.com';
+const xhrSendOptions = {
+    method: 'POST',
+    headers: {
+        headerA: 'headerValueA',
+    },
+    body: 'payload data',
+};
+const retryConfig = {
+    retry: 2,
+    retryDelay: 10,
+    shouldRetry: (data: ShouldRetryParam) => {
+        const { error, response } = data;
+        if (error) return true;
+        if (!response || !response.ok) return true;
+        return false;
+    },
+};
+const options = { ...xhrSendOptions, retryConfig };
+const response = await xhrSendRetry(url, options);
+```

package/packages/utils/src/addClass.ts

@@ -0,0 +1,9 @@
+import { Reference } from '@24i/bigscreen-sdk/jsx';
+
+export const addClass = (
+    reference: Reference,
+    className: string,
+): void => {
+    if (!reference.current) return;
+    reference.current.classList.add(className);
+};

package/packages/utils/src/counter.ts

@@ -0,0 +1,47 @@
+type CounterProps = {
+    triggerAt: number;
+    callback: () => void;
+};
+
+export interface ICounter {
+    /**
+     * Add number to counter value
+     * @param value Number to be added to counter value. If no number supplied,
+     * counter value is increased by 1.
+     */
+    add: (value?: number) => void,
+    /**
+     * @returns The current value of counter
+     */
+    getCurrentValue: () => number,
+    /**
+     * Check if `triggerAt` value is equal or greater than current value of counter.
+     * @returns True if `triggerAt` value is equal or greater than counter value.
+     */
+    isTriggered: () => boolean,
+    /**
+     * Check if number is equal to counter value
+     * @param value Number to be checked. If no number supplied,
+     * the `triggerAt` value is used to compare.
+     */
+    isEqual: (value?: number) => boolean,
+    /**
+     * Reset counter value, it is set to zero
+     */
+    reset: () => void,
+}
+
+export const createCounter = ({ triggerAt, callback }: CounterProps): ICounter => {
+    let counter = 0;
+    return {
+        add: (value = 1) => {
+            const oldCounter = counter;
+            counter += value;
+            if (oldCounter < triggerAt && counter >= triggerAt) callback();
+        },
+        getCurrentValue: () => counter,
+        isTriggered: () => counter >= triggerAt,
+        isEqual: (value: number = triggerAt) => counter === value,
+        reset: () => { counter = 0; },
+    };
+};

package/packages/utils/src/debounce.ts

@@ -0,0 +1,54 @@
+export type DebounceResult = {
+    cancel: () => void;
+    flush: () => void;
+};
+
+export type DebounceOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};
+
+export const debounce = <T extends any[], U extends (...args: T) => any>(
+    func: U,
+    debounceTime: number,
+    { leading, trailing }: DebounceOptions = { trailing: true },
+// eslint-disable-next-line sonarjs/cognitive-complexity
+): (...args: T) => DebounceResult => {
+    if (typeof func !== 'function') {
+        throw new Error('The first parameter of debounce must be a function');
+    }
+
+    const isLeading = !!leading;
+    const isTrailing = !!trailing || !isLeading;
+    let wasExecuted = false;
+    let timeoutID: number | null = null;
+    return ((...args: T) => {
+        wasExecuted = false;
+        if (timeoutID !== null) {
+            clearTimeout(timeoutID);
+        } else if (isLeading) {
+            func(...args);
+            wasExecuted = true;
+        }
+        timeoutID = window.setTimeout(() => {
+            if (isTrailing && !wasExecuted) {
+                func(...args);
+                wasExecuted = true;
+            }
+            timeoutID = null;
+        }, debounceTime);
+
+        return {
+            cancel: () => {
+                if (timeoutID === null) return;
+                clearTimeout(timeoutID);
+                timeoutID = null;
+            },
+            flush: () => {
+                if (timeoutID === null) return;
+                clearTimeout(timeoutID);
+                if (!wasExecuted) func(...args);
+            },
+        };
+    });
+};

package/packages/utils/src/displayToggler.scss

@@ -0,0 +1,3 @@
+.display-none {
+    display: none;
+}

package/packages/utils/src/displayToggler.ts

@@ -0,0 +1,38 @@
+import { Reference } from '@24i/bigscreen-sdk/jsx';
+import { addClass } from './addClass';
+import { removeClass } from './removeClass';
+import './displayToggler.scss';
+
+export const DISPLAY_NONE = 'display-none';
+
+export interface IDisplayToggler {
+    show: () => void,
+    hide: () => void,
+    isVisible: () => boolean,
+    isHidden: () => boolean,
+}
+
+export const getDisplayToggler = (
+    element: Reference<HTMLElement>,
+    initialIsHidden = false,
+): IDisplayToggler => {
+    let isHiddenFlag: boolean = initialIsHidden;
+
+    const show = () => {
+        if (!isHiddenFlag) return;
+        isHiddenFlag = false;
+        removeClass(element, DISPLAY_NONE);
+    };
+
+    const hide = () => {
+        if (isHiddenFlag) return;
+        isHiddenFlag = true;
+        addClass(element, DISPLAY_NONE);
+    };
+
+    const isVisible = () => !isHiddenFlag;
+
+    const isHidden = () => isHiddenFlag;
+
+    return { show, hide, isVisible, isHidden };
+};

package/packages/utils/src/elementUtils.ts

@@ -0,0 +1,58 @@
+import { Reference, unwrapReference } from '@24i/bigscreen-sdk/jsx';
+
+export const isElementVisible = (
+    elementOrReference: HTMLElement | Reference<HTMLElement>,
+) => {
+    const element = unwrapReference(elementOrReference);
+    if (!element) return false;
+    const style = window.getComputedStyle(element);
+    return style.display !== 'none' && style.visibility !== 'hidden';
+};
+
+export const isElementFullyVisible = (
+    elementOrReference: HTMLElement | Reference<HTMLElement>,
+) => {
+    const element = unwrapReference(elementOrReference);
+    if (isElementVisible(element)) {
+        let parent = element.parentElement;
+        while (parent) {
+            if (parent === document.body) {
+                return true;
+            }
+            if (!isElementVisible(parent)) {
+                return false;
+            }
+            parent = parent.parentElement;
+        }
+        return false;
+    }
+    return false;
+};
+
+export const isElementWrappedBy = (
+    elementOrReference: HTMLElement | Reference<HTMLElement>,
+    wrapperElementOrReferenceOrCondition:
+    HTMLElement | Reference<HTMLElement> | ((currentWrapper: HTMLElement) => boolean),
+    includesElementItself = false,
+) => {
+    const element = unwrapReference(elementOrReference);
+    let currentParent = includesElementItself ? element : element.parentElement;
+    let wrapperElement: HTMLElement | null = null;
+    let condition: ((currentWrapper: HTMLElement) => boolean) | null = null;
+    if (typeof wrapperElementOrReferenceOrCondition === 'function') {
+        condition = wrapperElementOrReferenceOrCondition;
+    } else {
+        wrapperElement = unwrapReference(wrapperElementOrReferenceOrCondition);
+        if (!wrapperElement) return false;
+    }
+    while (currentParent) {
+        if (condition && condition(currentParent)) {
+            return true;
+        }
+        if (currentParent === wrapperElement) {
+            return true;
+        }
+        currentParent = currentParent.parentElement;
+    }
+    return false;
+};

package/packages/utils/src/generateUuid.ts

@@ -0,0 +1,19 @@
+/* eslint-disable no-magic-numbers */
+/* eslint-disable no-nested-ternary */
+/* eslint-disable no-bitwise */
+
+/**
+ * Generates Universally Unique ID (UUIDv4 - RFC 4122)
+ * @returns universally unique identifier. Ex. "123e4567-e89b-12d3-a456-426614174000"
+ */
+export const generateUuid = (): string => {
+    let id = '';
+    for (let i = 0; i < 32; i++) {
+        const random = Math.random() * 16 | 0;
+        if (i === 8 || i === 12 || i === 16 || i === 20) {
+            id += '-';
+        }
+        id += (i === 12 ? 4 : (i === 16 ? ((random & 3) | 8) : random)).toString(16);
+    }
+    return id;
+};

package/packages/utils/src/index.ts

@@ -0,0 +1,35 @@
+export { generateUuid } from './generateUuid';
+export { stopEvent } from './stopEvent';
+export { noop } from './noop';
+export { offsetPosition } from './offsetPosition';
+export { addClass } from './addClass';
+export { removeClass } from './removeClass';
+export { debounce } from './debounce';
+export { wait } from './wait';
+export { scaledImage } from './scaledImage';
+export { nTimes } from './nTimes';
+export { getDisplayToggler, DISPLAY_NONE } from './displayToggler';
+export type { IDisplayToggler } from './displayToggler';
+export { getUsedJSHeapSize, getTotalJSHeapSize } from './memoryInfo';
+export {
+    isElementVisible,
+    isElementFullyVisible,
+    isElementWrappedBy,
+} from './elementUtils';
+export { createInterval, createTimeout, runAsync } from './timers';
+export type { TimedFunction } from './timers';
+export { createCounter } from './counter';
+export type { ICounter } from './counter';
+export {
+    DAY_IN_MS,
+    HOURS_PER_DAY,
+    HALF_HOUR_IN_MS,
+    HOUR_IN_MS,
+    MINUTES_PER_HALF_HOUR,
+    MINUTES_PER_HOUR,
+    MINUTE_IN_MS,
+    SECONDS_PER_MINUTE,
+    SECOND_IN_MS,
+} from './timeConstants';
+export { xhrSend, xhrSendRetry, defaultRetryConfig, mockXhr } from './xhr';
+export type { XhrOptions, XhrResponse, RetryConfig, RSOptions, ShouldRetryParam } from './xhr';

package/packages/utils/src/memoryInfo.ts

@@ -0,0 +1,21 @@
+/**
+ * The currently active segment size of JS heap, in bytes.
+ * @return {Number} size value. If size is unknown, returns 0.
+ */
+
+function getUsedJSHeapSize() {
+    return (window.performance as any)?.memory?.usedJSHeapSize as number || 0;
+}
+
+/**
+ * The total allocated heap size, in bytes.
+ * @return size value. If size is unknown, returns 0.
+ */
+function getTotalJSHeapSize() {
+    return (window.performance as any)?.memory?.totalJSHeapSize as number || 0;
+}
+
+export {
+    getUsedJSHeapSize,
+    getTotalJSHeapSize,
+};

package/packages/utils/src/nTimes.ts

@@ -0,0 +1,9 @@
+import { map } from '@24i/bigscreen-sdk/perf-utils/array';
+
+export const nTimes = <T>(
+    n: number,
+    mappingFunction: (_: undefined, index: number) => T,
+): T[] => {
+    const array = new Array(n);
+    return map(array, mappingFunction);
+};

package/packages/utils/src/noop.ts

@@ -0,0 +1 @@
+export const noop = () => {};