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

package/packages/perf-utils/README.md

@@ -0,0 +1,127 @@
+---
+id: README
+title: Performance Utils
+hide_title: true
+sidebar_label: Performance Utils
+---
+
+# Performance Utils
+Set of utilities that should increase a performance if they are used instead of a native way, mainly on older devices (e.g. Entone/Kamai set-top-boxes).
+
+> **Please check the limitations of each performance utility You want to use in a code.**
+
+## Available perf utils
+- **[Array](#array-perf-utils)**
+    - [filter](#filter)
+    - [forEach](#foreach)
+    - [includes](#includes)
+    - [includesNaN](#includesnan)
+    - [map](#map)
+  
+## Array perf utils
+
+> In general, each Array utility which requires a callback will iterate over all array items, even if array index hasn't been initialized yet (to understand the issue, see [An adventure in sparse arrays](https://remysharp.com/2018/06/26/an-adventure-in-sparse-arrays)).
+
+### filter()
+> The filter() method creates a new array with all elements that pass the test implemented by the provided function.  
+
+For more info, please see [native **filter** method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter).
+
+#### Limitations against native implementation
+- **`callback` is invoked for all indexes of the array** (not only for indexes with assigned values like [native filter implementation](http://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/filter#Description)).
+- **Doesn't coerce returned value from a callback to `true` or `false`**, the callback has to return a boolean value directly.
+- Doesn't accept the `scope` as last argument.
+
+#### Usage
+```javascript
+import { filter } from '@24i/bigscreen-sdk/perf-utils/array';
+
+const array = ['spray', 'limit', 'elite', 'exuberant', 'destruction'];
+//const result = array.filter(word => word.length > 6); // slower native solution
+const result = filter(array, word => word.length > 6);  // faster
+
+console.log(result);
+// expected output: Array ["exuberant", "destruction"]
+```
+
+### forEach()
+> The forEach() method executes a provided function once for each array element.
+
+For more info, please see [native **forEach** method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach).
+
+#### Limitations against native implementation
+- **`callback` is invoked for all indexes of the array** (not only for indexes with assigned values like [native forEach implementation](http://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach#Description)).
+- Doesn't accept the `scope` as last argument.
+
+#### Usage
+```javascript
+import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+
+const array = ['a', 'b', 'c'];
+// array.forEach(item => console.log(item)); // slower native solution
+forEach(array, item => console.log(item));   // faster
+
+// expected output: "a"
+// expected output: "b"
+// expected output: "c"
+```
+
+### includes()
+> The includes() method determines whether an array includes a certain value among its entries, returning true or false as appropriate.
+
+For more info, please see [native **includes** method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes).
+
+#### Limitations against native implementation
+- **Doesn't work for searching NaN value!** For that purpose, please use [includesNaN()](#includesnan).
+- Doesn't support negative indexes for `fromIndex` param - the entire array will be processed.
+
+#### Usage
+```javascript
+import { includes } from '@24i/bigscreen-sdk/perf-utils/array';
+
+const array = ['item0', 'item1', 'item2'];
+
+//console.log(array.includes('item1')); // slower native solution
+console.log(includes(array, 'item1'));  // faster
+// expected output: true
+
+//console.log(array.includes('item1')); // slower native solution
+console.log(includes(array, 'item1', 2));  // faster
+// expected output: false
+```
+
+### includesNaN()
+> The includesNaN() method determines whether an array includes NaN value among its entries, returning true or false as appropriate.
+
+#### Usage
+```javascript
+import { includesNaN } from '@24i/bigscreen-sdk/perf-utils/array';
+
+console.log(includesNaN([0, NaN, 1]));
+// expected output: true
+
+console.log(includesNaN([0, NaN, 1], 2));
+// expected output: false
+```
+
+### map()
+> The map() method creates a new array populated with the results of calling a provided function on every element in the calling array.
+
+For more info, please see [native **map** method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map).
+
+#### Limitations against native implementation
+- **`callback` is invoked for all indexes of the array** (not only for indexes with assigned values like [native map implementation](http://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/map#Description)).
+- Doesn't accept the `scope` as last argument.
+
+#### Usage
+```javascript
+import { map } from '@24i/bigscreen-sdk/perf-utils/array';
+
+const array = [1, 4, 9, 16];
+
+// const mappedArray = array.map(x => x * 2); // slower native solution
+const mappedArray = map(array, x => x * 2);   // faster
+
+console.log(mappedArray);
+// expected output: Array [2, 8, 18, 32]
+```

package/packages/perf-utils/src/array/filter.ts

@@ -0,0 +1,54 @@
+/**
+ * Performance optimized version of `Array.prototype.filter` method.
+ *
+ * Creates a new array with all elements that pass the test implemented by the provided function.
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/filter
+ *
+ * **Limitations against native implementation**:
+ *
+ * - **`callback` is invoked for all indexes of the array**,
+ * (not only for indexes with assigned values like native filter implementation), see example.
+ * - **Doesn't coerce returned value from a callback to `true` or `false`**,
+ * the callback has to return a boolean value directly.
+ * - Doesn't accept the `scope` as last argument.
+ *
+ * @param {Array} array - Input array.
+ * @param {Function} callback - Predicate to test each element of the array.
+ * Return true to keep the element, false otherwise.
+ *
+ * @return {Array} with filtered results.
+ *
+ * @example
+ * import { filter } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = ['spray', 'limit', 'elite', 'exuberant', 'destruction'];
+ *
+ * //const result = array.filter(word => word.length > 6); // slower native solution
+ * const result = filter(array, word => word.length > 6);  // faster
+ *
+ * console.log(result);
+ * // expected output: Array ["exuberant", "destruction"]
+ *
+ * @example
+ * import { filter } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const nativeResult = [1, 2, , undefined].filter(() => true);
+ * console.log(nativeResult); // Array [1, 2, undefined]. Yes, empty value is missing here.
+ *
+ * const customResult = filter([1, 2, , undefined], () => true);
+ * console.log(customResult); // Array [1, 2, undefined, undefined]. With iteration over hole.
+ */
+export const filter = <T>(
+    array: T[],
+    callback: (value: T, index: number, array: T[]) => boolean,
+): T[] => {
+    const output: T[] = [];
+
+    for (let i = 0, len = array.length; i < len; i++) {
+        if (callback(array[i], i, array) === true) {
+            output.push(array[i]);
+        }
+    }
+
+    return output;
+};

package/packages/perf-utils/src/array/find.ts

@@ -0,0 +1,43 @@
+/**
+ * Performance optimized version of `Array.prototype.find` method.
+ *
+ * Returns the first element that satisfies the testing function. Undefined if no item satisfies
+ * the testing function.
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/find
+ *
+ * **Limitations against native implementation**:
+ *
+ * - **`callback` is invoked for all indexes of the array**,
+ * (not only for indexes with assigned values like native filter implementation), see example.
+ * - **Doesn't coerce returned value from a callback to `true` or `false`**,
+ * the callback has to return a boolean value directly.
+ * - Doesn't accept the `scope` as last argument.
+ *
+ * @param {Array<T>} array - Input array.
+ * @param {Function} callback - Predicate to test each element of the array.
+ * Return true to select the element, false otherwise.
+ *
+ * @return {T | undefined} The first element the satisfied the testing function. Or undefined.
+ *
+ * @example
+ * import { find } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = ['spray', 'limit', 'elite', 'exuberant', 'destruction'];
+ *
+ * //const result = array.find(word => word.length > 6); // slower native solution
+ * const result = find(array, word => word.length > 6);  // faster
+ *
+ * console.log(result);
+ * // expected output: "exuberant"
+ */
+export const find = <T>(
+    array: T[],
+    callback: (value: T, index: number, array: T[]) => boolean,
+): T | undefined => {
+    for (let i = 0, len = array.length; i < len; i++) {
+        if (callback(array[i], i, array) === true) {
+            return array[i];
+        }
+    }
+    return undefined;
+};

package/packages/perf-utils/src/array/findIndex.ts

@@ -0,0 +1,43 @@
+/**
+ * Performance optimized version of `Array.prototype.findIndex` method.
+ *
+ * Returns the index of the first element that satisfies the testing function.
+ * Returns -1 if no item satisfies the testing function.
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
+ *
+ * **Limitations against native implementation**:
+ *
+ * - **`callback` is invoked for all indexes of the array**,
+ * (not only for indexes with assigned values like native filter implementation), see example.
+ * - **Doesn't coerce returned value from a callback to `true` or `false`**,
+ * the callback has to return a boolean value directly.
+ * - Doesn't accept the `scope` as last argument.
+ *
+ * @param {Array<T>} array - Input array.
+ * @param {Function} callback - Predicate to test each element of the array.
+ * Return true to select the index of the element, false otherwise.
+ *
+ * @return {number} Index of the first element the satisfied the testing function. Or -1.
+ *
+ * @example
+ * import { findIndex } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = ['spray', 'limit', 'elite', 'exuberant', 'destruction'];
+ *
+ * //const result = array.findIndex(word => word.length > 6); // slower native solution
+ * const result = findIndex(array, word => word.length > 6);  // faster
+ *
+ * console.log(result);
+ * // expected output: 3
+ */
+export const findIndex = <T>(
+    array: T[],
+    callback: (value: T, index: number, array: T[]) => boolean,
+): number => {
+    for (let i = 0, len = array.length; i < len; i++) {
+        if (callback(array[i], i, array) === true) {
+            return i;
+        }
+    }
+    return -1;
+};

package/packages/perf-utils/src/array/forEach.ts

@@ -0,0 +1,48 @@
+/**
+ * Performance optimized version of `Array.prototype.forEach` method.
+ *
+ * Executes a provided function once for each array element.
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
+ *
+ * **Limitations against native implementation**:
+ *
+ * - **`callback` is invoked for all indexes of the array**,
+ * (not only for indexes with assigned values like native filter implementation), see example.
+ * - Doesn't accept the scope as last argument.
+ *
+ * @param {Array} array - Input array.
+ * @param {Function} callback - Function to execute on each element.
+ *
+ * @return {void}
+ *
+ * @example
+ * import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = ['a', 'b', 'c'];
+ *
+ * // array.forEach(item => console.log(item)); // slower native solution
+ * forEach(array, item => console.log(item));   // faster
+ *
+ * // expected output: "a"
+ * // expected output: "b"
+ * // expected output: "c"
+ *
+ * @example
+ * import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = new Array(1000); // creates an empty array with length 1000
+ *
+ * let iNative = 0;
+ * array.forEach(() => iNative++);
+ * console.log(iNative); // 0 - the callback was never called
+ *
+ * let iCustom = 0;
+ * forEach(array, () => iCustom++);
+ * console.log(iCustom); // 1000 - the callback was called for each item (hole) in array
+ */
+
+export const forEach = <T>(array: T[], callback: (value: T, index: number, array: T[]) => void) => {
+    for (let i = 0, len = array.length; i < len; i++) {
+        callback(array[i], i, array);
+    }
+};

package/packages/perf-utils/src/array/includes.ts

@@ -0,0 +1,41 @@
+/**
+ * Performance optimized version of `Array.prototype.includes` method
+ * (doesn't work for searching NaN value).
+ *
+ * Determines whether an array includes a certain value among its entries,
+ * returning true or false as appropriate.
+
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
+ * @see includesNaN()
+ *
+ * **Limitations against native implementation**:
+ * - **Doesn't work for searching NaN value. For that purpose, please use includesNaN()**.
+ * - Doesn't accept the scope as last argument.
+ *
+ * @param {Array} array - Input array.
+ * @param {*} valueToFind - Value to find in array.
+ * @param {number} [fromIndex=0] - Index to start search from.
+ *
+ * @return {boolean}
+ *
+ * @example
+ * import { includes } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = ['item0', 'item1', 'item2'];
+ *
+ * //console.log(array.includes('item1')); // slower native solution
+ * console.log(includes(array, 'item1'));  // faster
+ * // expected output: true
+ *
+ * //console.log(array.includes('item1')); // slower native solution
+ * console.log(includes(array, 'item1', 2));  // faster
+ * // expected output: false
+ */
+export const includes = <T>(array: T[], valueToFind: T, fromIndex = 0): boolean => {
+    for (let i = fromIndex, len = array.length; i < len; i++) {
+        if (array[i] === valueToFind) {
+            return true;
+        }
+    }
+    return false;
+};

package/packages/perf-utils/src/array/includesNaN.ts

@@ -0,0 +1,32 @@
+/**
+ * Performance optimized version of `Array.prototype.includes` method for testing `NaN` value.
+ *
+ * Determines whether an array includes NaN value among its entries,
+ * returning true or false as appropriate.
+ *
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/includes
+ *
+ * @param {Array} array - Input array.
+ * @param {number} [fromIndex=0] - Index to start search from.
+ *
+ * @return {boolean}
+ *
+ * @example
+ * import { includesNaN } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * // returns true
+ * includesNaN([0, NaN, 2]);
+ *
+ * // returns false
+ * includesNaN([0, NaN, 2], 2);
+ */
+export const includesNaN = (array: any[], fromIndex = 0): boolean => {
+    for (let i = fromIndex, len = array.length; i < len; i++) {
+        const iValue = array[i];
+        // eslint-disable-next-line no-self-compare
+        if (iValue !== iValue) { // true only for NaN value
+            return true;
+        }
+    }
+    return false;
+};

package/packages/perf-utils/src/array/index.ts

@@ -0,0 +1,7 @@
+export { filter } from './filter';
+export { find } from './find';
+export { findIndex } from './findIndex';
+export { forEach } from './forEach';
+export { includes } from './includes';
+export { includesNaN } from './includesNaN';
+export { map } from './map';

package/packages/perf-utils/src/array/map.ts

@@ -0,0 +1,52 @@
+/**
+ * Performance optimized version of `Array.prototype.map` method.
+ *
+ * Creates a new array populated with the results of calling a provided function
+ * on every element in the calling array.
+ *
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array/map
+ *
+ * **Limitations against native implementation**:
+ *
+ * - **`callback` is invoked for all indexes of the array**,
+ * (not only for indexes with assigned values like native filter implementation), see example.
+ * - Doesn't accept the `scope` as last argument.
+ *
+ * @param {Array} array - Input array.
+ * @param {Function} callback - Function that is called for every element of arr.
+ * Each time callback executes, the returned value is added to output array.
+ *
+ * @return {Array} with mapped results.
+ *
+ * @example
+ * import { map } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = [1, 4, 9, 16];
+ *
+ * // const mappedArray = array.map(x => x * 2); // slower native solution
+ * const mappedArray = map(array, x => x * 2);   // faster
+ *
+ * console.log(mappedArray);
+ * // expected output: Array [2, 8, 18, 32]
+ *
+ * @example
+ * import { map } from '@24i/bigscreen-sdk/perf-utils/array';
+ *
+ * const array = [1, , 2].map(x => x * x) // [ 1, , 4 ]
+ *
+ * const nativeResult = array.map(x => x * x);
+ * console.log(nativeResult); // [ 1, , 4 ] // keeps hole in array
+ *
+ * const customResult = map(array, x => x * x);
+ * console.log(customResult); // [ 1, NaN , 4 ] NaN? -> undefined * undefined = NaN
+ */
+export const map = <T, M>(array: T[], callback: (item: T, index: number, array: T[]) => M): M[] => {
+    const len = array.length;
+    const output = new Array(len);
+
+    for (let i = 0; i < len; i++) {
+        output[i] = callback(array[i], i, array);
+    }
+
+    return output;
+};

package/packages/picker/README.md

@@ -0,0 +1,70 @@
+---
+id: README
+title: Picker
+hide_title: true
+sidebar_label: Picker
+---
+
+# Picker
+Picker is a component that works like a select in classic HTML and its purpose is to select 1 option.
+
+## Basic Usage
+```tsx
+<Picker
+    data={[
+        { label: 'Option 1', value: 1 },
+        { label: 'Option 2', value: 2 },
+        { label: 'Option 3', value: 3 },
+        { label: 'Option 4', value: 4 },
+    ]}
+    selectedValue={2}
+    visibleItems={3}
+    scrollStep={10}
+    onValueChange={this.onOptionSelected}
+    modalService={modalServiceRef}
+/>
+```
+
+## Props&lt;T&gt;
+- data - array of `{ label: string, value: T }`
+- selectedValue - `T`
+- visibleItems - number of visibleItems (for the underlying List)
+- scrollStep - number of pixels to scroll (for the underlying List)
+- onValueChange - callback called when new value is selected `(newValue: T) => void`
+- modalService - `Reference<Modal>` - reference to your app's modal service instance
+- mode? - Mode of the Picker, defaults to `Picker.MODAL`, supported modes: `Picker.MODAL`
+- className? - string class name passed to underlying DOM component
+- modalClassName? - string class name passed to picker modal which is added after `picker-modal` class name
+- Checkbox? - `ICheckbox<{ checked: boolean }>` - possibility to modify Checkbox component
+- render? - custom render method, when you need more complex button with separate label inside
+
+## Special Pickers
+
+### DatePicker
+Special Picker for selecting a Date from an interval.
+
+** Props **
+Same as classic Picker without `data`, plus:
+- from - timestamp as the 1st day in the interval
+- to - timestamp as the last day in the interval
+- selectedValue - timestamp
+- format? - a function to format label from value `(value: Date) => string`
+- overrides? - object with overriding labels `Record<number, string>` in format `{ [oldLabel]: newLabel }`
+- className? - when no className prop is defined, class `date-picker` is automatically added
+
+** Example **
+```tsx
+<DatePicker
+    from={new Date('1/1/2010').getTime()}
+    to={new Date('1/15/2010').getTime()}
+    selectedValue={new Date('1/8/2010').getTime()}
+    visibleItems={10}
+    scrollStep={10}
+    onValueChange={jest.fn()}
+    modalService={createRef(modalServiceMock as unknown as ModalService)}
+    format={(date) => date.toISOString().split('T')[0]}
+    overrides={{
+        '1262908800000': 'Today',
+    }}
+/>,
+```

package/packages/picker/src/DatePicker.tsx

@@ -0,0 +1,55 @@
+import { FC, forwardRef } from '@24i/bigscreen-sdk/jsx';
+import { Props as PickerProps, Picker } from './Picker';
+import { Data } from './types';
+
+const ONE_DAY = 86400000;
+
+type Overrides = Record<number, string>;
+
+type Props = Omit<PickerProps<number>, 'data'> & {
+    from: number,
+    to: number,
+    /* eslint-disable react/require-default-props */
+    overrides?: Overrides,
+    format?: (date: Date) => string,
+    /* eslint-enable react/require-default-props */
+};
+
+const formatDate = (date: Date) => {
+    if (typeof date.toLocaleDateString === 'function') return date.toLocaleDateString();
+    return date.toDateString();
+};
+
+const getDateData = (
+    from: number, to: number, overrides: Overrides = {}, format = formatDate,
+): Data<number> => {
+    const values = [from];
+    let current = from + ONE_DAY;
+    while (current < to) {
+        values.push(current);
+        current += ONE_DAY;
+    }
+    values.push(to);
+    return values.map((value) => ({
+        label: overrides[value] || format(new Date(value)),
+        value,
+    }));
+};
+
+const DatePicker: FC<Props> = forwardRef(({
+    from, to, overrides, format, selectedValue, className = 'date-picker',
+    ...restProps
+}: Props, ref) => {
+    const data = getDateData(from, to, overrides, format);
+    return (
+        <Picker
+            ref={ref}
+            {...restProps}
+            data={data}
+            className={className}
+            selectedValue={selectedValue}
+        />
+    );
+});
+
+export { DatePicker };

package/packages/picker/src/ModalPicker/Checkbox.tsx

@@ -0,0 +1,38 @@
+import { Children, Component, createRef, DeclareProps } from '@24i/bigscreen-sdk/jsx';
+import { getDisplayToggler, DISPLAY_NONE } from '@24i/bigscreen-sdk/utils/displayToggler';
+import { ICheckbox } from '../types';
+
+type Props = {
+    checked: boolean,
+    checkmark?: Children,
+};
+
+export class Checkbox extends Component<Props> implements ICheckbox<Props> {
+    span = createRef<HTMLSpanElement>();
+
+    // eslint-disable-next-line react/destructuring-assignment
+    display = getDisplayToggler(this.span, !this.props.checked);
+
+    static defaultProps = {
+        checkmark: '✓',
+    };
+
+    declare props: DeclareProps<Props, typeof Checkbox.defaultProps>;
+
+    check() {
+        this.display.show();
+    }
+
+    uncheck() {
+        this.display.hide();
+    }
+
+    render() {
+        const { checked, checkmark } = this.props;
+        return (
+            <span ref={this.span} className={`checkbox ${checked ? '' : DISPLAY_NONE}`}>
+                {checkmark}
+            </span>
+        );
+    }
+}