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

package/packages/list/src/utils.ts

@@ -0,0 +1,142 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { offsetPosition } from '@24i/bigscreen-sdk/utils/offsetPosition';
+import { forEach, map } from '@24i/bigscreen-sdk/perf-utils/array';
+import { ListBase } from './Base';
+import { AnimationConfiguration, ItemInfo } from './types';
+
+export const configureAnimation = (
+    defaultAnimation: AnimationConfiguration,
+    propsAnimation: Partial<AnimationConfiguration>,
+): AnimationConfiguration => ({
+    normal: {
+        time: propsAnimation.normal?.time || defaultAnimation.normal.time,
+        easing: propsAnimation.normal?.easing || defaultAnimation.normal.easing,
+    },
+    // eslint-disable-next-line no-nested-ternary
+    fastLinear: propsAnimation.fastLinear ? {
+        time: propsAnimation.fastLinear.time,
+        startRatio: propsAnimation.fastLinear.startRatio,
+        endRatio: propsAnimation.fastLinear.endRatio,
+    } : defaultAnimation.fastLinear ? {
+        time: defaultAnimation.fastLinear.time,
+        startRatio: defaultAnimation.fastLinear.startRatio,
+        endRatio: defaultAnimation.fastLinear.endRatio,
+    } : undefined,
+    slowdownRatio: propsAnimation.slowdownRatio || defaultAnimation.slowdownRatio || undefined,
+});
+
+export const getOffsetObject = (horizontal: boolean | undefined, offset: number) => (
+    { [horizontal ? 'x' : 'y']: offset }
+);
+
+export const prepareAnimatedItems = (list: ListBase<any, any>): ItemInfo[] => {
+    const childNodes = Array.prototype.slice.call(
+        list.scroller.current!.scrollRef.current!.childNodes,
+    );
+    return map(childNodes, (element: HTMLElement, dataIndex: number) => ({
+        element: createRef<HTMLElement>(element),
+        dataIndex,
+        offset: 0,
+    }));
+
+};
+
+export const changeItemsOffsetBy = (
+    items: ItemInfo[], offsetDiff: number, horizontal: boolean | undefined,
+) => {
+    forEach(items, (item) => {
+        item.offset += offsetDiff;
+        offsetPosition(item.element, getOffsetObject(horizontal, item.offset));
+    });
+};
+
+/**
+ * To determine maximum number of visible items in list's viewport.
+ * @param viewportSizePx Size (in pixels) of list's viewport. For vertical list,
+ * use height size.
+ * @param minItemSizePx Size (in pixels) of item in list. If list can contain
+ * items with different size, use the smallest item size.
+ */
+export const calcVisibleItemCount = (viewportSizePx: number, minItemSizePx: number) => (
+    // eslint-disable-next-line no-magic-numbers
+    Math.ceil((viewportSizePx / minItemSizePx) + 0.5)
+);
+
+/**
+ * Calculates offsets of items based on given item sizes.
+ * Offset defines position, to place an item relative to the edge of an root's box.
+ * @param itemsSizesPx Sizes in pixels of items
+ * @returns Offsets of items
+ */
+export const prepareOffsetsPx = (itemsSizesPx: number[]) => {
+    const offsets = [];
+    let offsetAccumulator = 0;
+    for (let i = 0; i < itemsSizesPx.length; i++) {
+        offsets.push(offsetAccumulator);
+        offsetAccumulator += itemsSizesPx[i];
+    }
+    return offsets;
+};
+
+/**
+ * Pre-calculates scroll offsets of items based on given item sizes and first scroll step.
+ * Offset defines position, to place an item relative to the edge of an root's box.
+ * @param itemsSizesPx Sizes in pixels of items
+ * @param firstScrollStepPx
+ * @returns Scroll offsets of items including first scroll step correction
+ */
+export const prepareScrollOffsetsPx = (itemsSizesPx: number[], firstScrollStepPx: number) => {
+    const offsets = [];
+    let offsetAccumulator = 0;
+
+    if (!itemsSizesPx.length) {
+        return [];
+    }
+
+    const visiblePartPx = firstScrollStepPx
+        ? itemsSizesPx[0] - firstScrollStepPx
+        : 0;
+
+    // for first item
+    offsets.push(0);
+    offsetAccumulator += itemsSizesPx[0];
+
+    // for next others
+    for (let i = 1; i < itemsSizesPx.length; i++) {
+        offsets.push(offsetAccumulator - visiblePartPx);
+        offsetAccumulator += itemsSizesPx[i];
+    }
+    return offsets;
+};
+
+/**
+ * Convert Scroll position in pixels to Scroll index.
+ * @param pixels Scroll position in pixels (expect positive number)
+ * @param scrollStep Size in pixels for one step of scroller
+ * @param firstScrollStep Size in pixels for first scroller step
+ * @returns scroll index
+ */
+export const scrollPixelsToIndexForward = (
+    pixels: number, scrollStep: number, firstScrollStep?: number,
+) => {
+    if (pixels === 0) return 0;
+    if (typeof firstScrollStep === 'undefined') return Math.ceil(pixels / scrollStep);
+    if (pixels <= firstScrollStep) return 1;
+    return Math.ceil((pixels - firstScrollStep) / scrollStep) + 1;
+};
+
+/**
+ * Convert Scroll position in pixels to Scroll index.
+ * @param pixels Scroll position in pixels (expect positive number)
+ * @param scrollStep Size in pixels for one step of scroller
+ * @param firstScrollStep Size in pixels for first scroller step
+ * @returns scroll index
+ */
+export const scrollPixelsToIndexBackward = (
+    pixels: number, scrollStep: number, firstScrollStep?: number,
+) => {
+    if (pixels === 0) return 0;
+    if (typeof firstScrollStep === 'undefined') return Math.floor(pixels / scrollStep);
+    if (pixels <= firstScrollStep) return 0;
+    return Math.floor((pixels - firstScrollStep) / scrollStep) + 1;
+};

package/packages/logger/README.md

@@ -0,0 +1,117 @@
+---
+id: README
+title: Logger
+hide_title: true
+sidebar_label: Logger
+---
+
+# Logger
+
+Minimal and lightweight logger tools for SmartApps BIGscreen applications.
+
+## Basic Usage
+
+```ts
+import { LoggerManager, ConsoleLogger } from '@24i/bigscreen-sdk/logger';
+
+LoggerManager.add([
+    new ConsoleLogger(),
+]);
+
+const Logger = LoggerManager.getLoggerService();
+
+Logger.debug('debug message');
+Logger.info('info message');
+Logger.warn('warn message');
+Logger.error('error message');
+```
+
+Logging methods also include an options parameter by which we can better specify the context of the message or add additional data.
+Individual Loggers have their own approach to how they handle these options.
+
+```ts
+interface LogOptions {
+    category?: LogCategory;
+    additionalData?: any;
+}
+```
+
+So, for example, in this case:
+
+```ts
+import { LogCategory } from '@24i/bigscreen-sdk/logger';
+
+Logger.warn('Data refresh failed', { category: 'api', additionalData: { statusCode: 401 } });
+```
+
+the output would be:
+
+```ts
+[API] Data refresh failed {
+    "statusCode": 401
+}
+```
+
+## Logger Manager
+
+Logger Manager is used for managing loggers. We are able to add individual loggers to the Logger Manager and perform various operations on them.
+All loggers that we want to add to the Logger Manager should inherit from the [LoggerBase](./src/loggers/LoggerBase/README.md) abstract class.
+
+### Methods
+
+- `add(loggerInstance: LoggerBase | LoggerBase[]): void` - Adds the logger to the Logger Manager.
+- `setLevels(config: LevelConfig[]): void` - Defines the log levels on which we want to log. Other levels will be ignored.
+
+    ```ts
+    LoggerManager.setLevels([
+        {
+            loggerName: 'ConsoleLogger',
+            levels: ['debug', 'info'],
+        },
+        {
+            loggerName: 'SentryLogger',
+            levels: ['warn', 'error'],
+        },
+    ]);
+    ```
+
+- `getLogger(loggerName: string): LoggerBase | null` - Returns the logger instance by name.
+- `mute(loggerName: string): void` - Mutes the logger by the name.
+- `muteAll(): void` - Mutes all loggers.
+- `getLoggerService(): LoggerService` - Returns the Logger Service.
+
+## Logger Service
+
+Logger Service works as a log trigger. It goes through all the loggers added in LogManager and runs logging methods on them.
+
+```ts
+const Logger = LoggerManager.getLoggerService();
+Logger.info('info message');
+```
+
+If we want to log messages only on some loggers, we can specify them in the log options parameter.
+
+```ts
+const Logger = LoggerManager.getLoggerService();
+Logger.info('info message', { onlyLoggers: ['ConsoleLogger'] });
+```
+
+## Enums
+
+Together with logger tools and individual loggers, this package defines enums for log levels and log categories.
+
+### Log Level
+
+The log message is assigned a level, which determines how urgent it is. The following log levels are defined:
+
+```ts
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+```
+
+### Log Category
+
+The log messages should be categorized according to what caused them. The following log categories are defined:
+
+```ts
+type LogCategory = 'ui' | 'api' | 'player' | 'middleware' | 'error' | 'debug';
+```

package/packages/logger/src/LoggerManager.ts

@@ -0,0 +1,60 @@
+import { forEach } from '@24i/bigscreen-sdk/perf-utils/array';
+import { LoggerBase } from './loggers/LoggerBase';
+import { LoggerService } from './LoggerService';
+import { LevelConfig } from './types';
+
+class LoggerManager {
+    private loggers: Record<string, LoggerBase> = {};
+
+    private readonly loggerService: LoggerService = new LoggerService(this.loggers);
+
+    private addOne(loggerInstance: LoggerBase) {
+        const loggerName = loggerInstance.getName();
+        this.loggers[loggerName] = loggerInstance;
+    }
+
+    add(loggerInstance: LoggerBase | LoggerBase[]) {
+        if (loggerInstance instanceof Array) {
+            forEach(loggerInstance, (logger) => {
+                this.addOne(logger);
+            });
+        } else {
+            this.addOne(loggerInstance);
+        }
+    }
+
+    setLevels(config: LevelConfig[]) {
+        forEach(config, (levelConfig) => {
+            const { loggerName, levels } = levelConfig;
+            const loggerInstance = this.getLogger(loggerName);
+            if (loggerInstance) loggerInstance.setLevels(levels);
+        });
+    }
+
+    getLogger(loggerName: string) {
+        const logger = this.loggers[loggerName];
+        if (logger) return logger;
+        return null;
+    }
+
+    mute(loggerName: string) {
+        const loggerInstance = this.getLogger(loggerName);
+        if (loggerInstance) loggerInstance.muteLogger();
+    }
+
+    muteAll() {
+        const { loggers } = this;
+        const loggerNames = Object.keys(loggers);
+
+        forEach(loggerNames, (loggerName) => {
+            const loggerInstance = loggers[loggerName];
+            loggerInstance.muteLogger();
+        });
+    }
+
+    getLoggerService() {
+        return this.loggerService;
+    }
+}
+
+export const loggerManager = new LoggerManager();

package/packages/logger/src/LoggerService.ts

@@ -0,0 +1,43 @@
+import { filter, forEach, includes } from '@24i/bigscreen-sdk/perf-utils/array';
+import { ILogger, ServiceLogOptions, LogLevel } from './types';
+import { LoggerBase } from './loggers/LoggerBase';
+
+export class LoggerService implements ILogger {
+    constructor(
+        private readonly loggerInstances: Record<string, LoggerBase>,
+    ) {}
+
+    debug(message: string, options?: ServiceLogOptions) {
+        this.logTrigger('debug', message, options);
+    }
+
+    info(message: string, options?: ServiceLogOptions) {
+        this.logTrigger('info', message, options);
+    }
+
+    warn(message: string, options?: ServiceLogOptions) {
+        this.logTrigger('warn', message, options);
+    }
+
+    error(message: string, options?: ServiceLogOptions) {
+        this.logTrigger('error', message, options);
+    }
+
+    private logTrigger(
+        level: LogLevel,
+        message: string,
+        options: ServiceLogOptions = {},
+    ) {
+        const { loggerInstances } = this;
+        let loggerNames = Object.keys(loggerInstances);
+        const { onlyLoggers } = options;
+        if (onlyLoggers) {
+            loggerNames = filter(loggerNames, (loggerName) => includes(onlyLoggers, loggerName));
+        }
+
+        forEach(loggerNames, (loggerName) => {
+            const logger = loggerInstances[loggerName];
+            logger[level]?.(message, options);
+        });
+    }
+}

package/packages/logger/src/index.ts

@@ -0,0 +1,3 @@
+export { loggerManager as LoggerManager } from './LoggerManager';
+export { ConsoleLogger, SentryLogger } from './loggers';
+export { LogLevel, LogCategory } from './types';

package/packages/logger/src/loggers/ConsoleLogger/ConsoleLogger.ts

@@ -0,0 +1,51 @@
+/* eslint-disable no-console */
+import { LoggerBase, Config as LoggerBaseConfig } from '../LoggerBase';
+import { LogOptions, LogLevel } from '../../types';
+
+type Config = {};
+
+const defaultConfig: LoggerBaseConfig<Config> = {
+    name: 'ConsoleLogger',
+};
+
+const LOG_MESSAGE_SPACE_SIZE = 4;
+
+export class ConsoleLogger extends LoggerBase {
+    constructor(config: LoggerBaseConfig<Config> = {}) {
+        super({ ...defaultConfig, ...config });
+    }
+
+    debug(message: string, options?: LogOptions) {
+        this.logMessage('debug', message, options);
+    }
+
+    info(message: string, options?: LogOptions) {
+        this.logMessage('info', message, options);
+    }
+
+    warn(message: string, options?: LogOptions) {
+        this.logMessage('warn', message, options);
+    }
+
+    error(message: string, options?: LogOptions) {
+        this.logMessage('error', message, options);
+    }
+
+    private logMessage(
+        level: LogLevel,
+        message: string,
+        { category, additionalData }: LogOptions = {},
+    ) {
+        if (this.isMuted() || this.isBlockedByLevel(level)) return;
+        const logFunction = console[level];
+        if (typeof logFunction !== 'function') return;
+
+        let errorMessage = category ? `[${category.toUpperCase()}] ${message}` : message;
+        if (additionalData) {
+            if (additionalData.message) errorMessage += ` - ${additionalData.message}`;
+            logFunction(errorMessage, JSON.stringify(additionalData, null, LOG_MESSAGE_SPACE_SIZE));
+        } else {
+            logFunction(errorMessage);
+        }
+    }
+}

package/packages/logger/src/loggers/ConsoleLogger/README.md

@@ -0,0 +1,39 @@
+---
+id: README
+title: Console Logger
+hide_title: true
+sidebar_label: Console Logger
+---
+
+# Console Logger
+
+Basic logger that uses the Console Web API as log output.
+
+## Config
+
+```ts
+type Config = {};
+
+const defaultConfig: LoggerBaseConfig<Config> = {
+    name: 'ConsoleLogger',
+};
+
+```
+
+## Example
+
+```ts
+import { ConsoleLogger } from '@24i/bigscreen-sdk/logger/ConsoleLogger'
+
+const consoleLogger = new ConsoleLogger();
+
+consoleLogger.info('Data refreshed', { 'api', additionalData: { statusCode: 200 } });
+```
+
+Output:
+
+```ts
+[API] Data refreshed {
+    "statusCode": 200
+}
+```

package/packages/logger/src/loggers/ConsoleLogger/index.ts

@@ -0,0 +1 @@
+export { ConsoleLogger } from './ConsoleLogger';

package/packages/logger/src/loggers/LoggerBase/LoggerBase.ts

@@ -0,0 +1,67 @@
+import { includes } from '@24i/bigscreen-sdk/perf-utils/array';
+import { ILogger, LogOptions, LogLevel } from '../../types';
+
+export type Config<T = {}> = Partial<{
+    name: string;
+    mute: boolean;
+    levels: LogLevel[];
+}> & T;
+
+const defaultConfig: Config = {
+    name: 'Logger',
+    mute: false,
+    levels: [],
+};
+
+export abstract class LoggerBase implements ILogger {
+    protected name: string;
+
+    protected mute: boolean;
+
+    protected levels: LogLevel[];
+
+    constructor(config: Config = {}) {
+        const mergedConfig = { ...defaultConfig, ...config };
+        const { name, mute, levels } = mergedConfig;
+
+        this.name = name!;
+        this.mute = mute!;
+        this.levels = levels!;
+    }
+
+    abstract debug(message: string, options?: LogOptions): void;
+
+    abstract info(message: string, options?: LogOptions): void;
+
+    abstract warn(message: string, options?: LogOptions): void;
+
+    abstract error(message: string, options?: LogOptions): void;
+
+    setName(name: string) {
+        this.name = name;
+    }
+
+    getName() {
+        return this.name;
+    }
+
+    setLevels(levels: LogLevel[]) {
+        this.levels = levels;
+    }
+
+    getLevels() {
+        return this.levels;
+    }
+
+    muteLogger() {
+        this.mute = true;
+    }
+
+    isMuted() {
+        return this.mute;
+    }
+
+    isBlockedByLevel(level: LogLevel) {
+        return this.levels.length && !includes(this.levels, level);
+    }
+}

package/packages/logger/src/loggers/LoggerBase/README.md

@@ -0,0 +1,69 @@
+---
+id: README
+title: LoggerBase
+hide_title: true
+sidebar_label: LoggerBase
+---
+
+# LoggerBase
+
+It is an abstract class from which loggers should inherit.
+All loggers must be implemented so that they can be used separately or with the use of SmartApps BIGscreen logging tools.
+LoggerBase abstract class implements *ILogger* interface.
+
+```ts
+interface ILogger {
+    debug: LogMethod;
+    info: LogMethod;
+    warn: LogMethod;
+    error: LogMethod;
+}
+
+type LogMethod = (message: string, options?: LogOptions) => void;
+
+interface LogOptions {
+    category?: LogCategory;
+    additionalData?: any;
+}
+```
+
+## Config
+
+All config properties are optional.
+
+```ts
+export type Config<T = {}> = Partial<{
+    name: string;
+    mute: boolean;
+    levels: LogLevel[];
+}> & T;
+
+const defaultConfig: Config = {
+    name: 'Logger',
+    mute: false,
+    levels: [],
+};
+```
+
+- `name` - Name of the logger. Keep in mind, that each logger should have a unique name.
+- `mute` - Mute status.
+- `level` - Levels at which the logger can log. If it is empty, it can log at all levels.
+
+## Methods
+
+- `abstract debug(message: string, options?: LogOptions): void` - Log method with log level: debug.
+- `abstract info(message: string, options?: LogOptions): void` - Log method with log level: info.
+- `abstract warn(message: string, options?: LogOptions): void` - Log method with log level: warn.
+- `abstract error(message: string, options?: LogOptions): void` - Log method with log level: error.
+- `setName(name: string): void` - Sets the name of the logger.
+- `getName(): string` - Returns the name of the logger.
+- `setLevels(levels: LogLevel[]): void` - Sets allowed log levels.
+- `getLevels(): LogLevel[]` - Returns allowed log levels.
+- `muteLogger(): void` - Mutes the logger.
+- `isMuted(): boolean` - Indicates whether the logger is muted.
+- `isBlockedByLevel(level: LogLevel): boolean` - Indicates whether the logger is blocked by level.
+
+## Prepared Loggers
+
+- [ConsoleLogger](../ConsoleLogger/README.md)
+- [SentryLogger](../SentryLogger/README.md)

package/packages/logger/src/loggers/LoggerBase/index.ts

@@ -0,0 +1 @@
+export { Config, LoggerBase } from './LoggerBase';

package/packages/logger/src/loggers/SentryLogger/README.md

@@ -0,0 +1,98 @@
+---
+id: README
+title: Sentry Logger
+hide_title: true
+sidebar_label: Sentry Logger
+---
+
+# Sentry Logger
+
+Sentry integration for SmartApps BIGscreen logger tools.
+
+## Config
+
+```ts
+type Config = {
+    sentryOptions: Sentry.BrowserOptions;
+    storage?: IStorage;
+    loggerEnvironment?: SentryLoggerEnvironment;
+};
+
+const defaultConfig: LoggerBaseConfig<Partial<Config>> = {
+    name: 'SentryLogger',
+};
+```
+
+- `sentryOptions` - Sentry configuration (<https://docs.sentry.io/platforms/javascript/configuration/options/>).
+- `storage` - Currently used storage instance (default: [LocalStorage](../../../../storage/README.md)).
+- `loggerEnvironment` - Information about the environment that is sent to the logger.
+
+    ```ts
+    interface SentryLoggerEnvironment {
+        [key: string]: string;
+        device: string;
+        platformName: string;
+        platformVersion: string;
+        serialNumber: string;
+        firmware: string;
+        macAddress: string;
+        flavour: string;
+        resolution: string;
+        player: string;
+    }
+    ```
+
+## Useful Methods
+
+- `setUser(user: Sentry.User): void` - Sets unique identity in Sentry (e.g. Login).
+- `removeUser(): void` - Removes user identity (e.g. Logout).
+- `addBreadcrumb(breadcrumb: Sentry.Breadcrumb): void` - Records small pieces of structured data that is attached to a log message.
+- `setTag(key: string, value: string): void` - Sets string pairs that are both indexed and searchable.
+- `clearScope(): void` - Clears current scope (breadcrumbs, extras, tags...).
+
+## Sentry
+
+If you need to import the Sentry.io library (because of e.g. types or integration), you should do it directly from
+Sentry Logger. This avoids potential Sentry.io version incompatibilities and at the same time, you can use this Sentry instance (which is used by Sentry Logger) and perform custom operations on it.
+
+```ts
+import { Sentry } from '@24i/bigscreen-sdk/logger/SentryLogger'
+```
+
+## Example
+
+```ts
+import { device } from '@24i/bigscreen-sdk/device';
+import { SentryLogger, Sentry } from '@24i/bigscreen-sdk/logger/SentryLogger'
+import { HTML5Video } from '@24i/player-html5';
+import { APP_CONFIG_ID, APP_RESOLUTION } from '../../configNxgTV';
+
+const loggerEnvironment = {
+    device: await device.getDeviceName(),
+    platformName: await device.getPlatformName(),
+    platformVersion: await device.getPlatformVersion(),
+    serialNumber: await device.getUuid(),
+    firmware: await device.getFirmware(),
+    macAddress: await device.getMacAddress(),
+    flavour: APP_CONFIG_ID,
+    resolution: APP_RESOLUTION,
+    player: `${HTML5Video.playerName} ${HTML5Video.version}`,
+};
+
+const sentryConfig = {
+    mute: environment === 'development',
+    storage: Storage,
+    sentryOptions: {
+        dsn: 'https://fake-dsn@sentry.24imedia.tv/1',
+        release: `fake-app@0.0.1`,
+        integrations: [new Sentry.Integrations.Breadcrumbs({
+            fetch: false,
+        })],
+    },
+    loggerEnvironment,
+};
+
+const sentryLogger = new SentryLogger(sentryConfig);
+
+sentryLogger.info('Data refreshed', { category: 'api', additionalData: { statusCode: 200 } });
+```