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

package/packages/types-bigscreen-jsx/src/copyTypes.js

@@ -0,0 +1,14 @@
+const fs = require('fs');
+
+const indexPath = './node_modules/@types/react/index.d.ts';
+const globalPath = './node_modules/@types/react/global.d.ts';
+const indexTarget = './packages/types-bigscreen-jsx/index.d.ts';
+const globalTarget = './packages/types-bigscreen-jsx/global.d.ts';
+
+if (fs.existsSync(indexPath) && fs.existsSync(globalPath)) {
+    fs.copyFileSync(indexPath, indexTarget);
+    fs.copyFileSync(globalPath, globalTarget);
+} else {
+    console.error('Failed to get extended react typings.');
+    process.exit(1);
+}

package/packages/volume-control/README.md

@@ -0,0 +1,79 @@
+---
+id: README
+title: Volume Control
+hide_title: true
+sidebar_label: Volume Control
+---
+
+# Volume Control
+The volume control allows you to manipulate the volume. It provides the service and default component
+that are needed for interaction and control. Volume is controlled inside range from 0 to 100, where
+100 is the highest volume, 0 is silent.
+
+## Volume Control Service
+
+The Volume Control Service acts as middleware between the user interaction and the GUI.
+It registers keyDown events, keeps the sound state and renders the Volume Control UI.
+
+### Usage
+
+```tsx
+import { VolumeControlService, VolumeControlUI } from '@24i/bigscreen-sdk/volume-control';
+
+const App = () => (
+    <div id="app">
+        <VolumeControlService volumeControlUI={(ref) => <VolumeControlUI ref={ref} />} />
+    </div>
+);
+```
+
+### VolumeControlService Props
+
+```ts
+type Props = {
+    volumeStep?: number;
+    displayTimeInMs?: number;
+    volumeControlUI: (ref: Reference) => JSX.Element;
+};
+```
+
+- `volumeStep` - Allows you to adjust the increment/decrement step of volume (default: `10`)
+- `displayTimeInMs` - Time in milliseconds for which the Volume Control UI will be displayed (default: `3000`).
+- `volumeControlUI` - Render function for volume control UI.
+
+### VolumeControlUI Props
+
+```ts
+type Props = {
+    showVolumeText?: boolean;
+    animationTimeInMs?: number;
+    icons?: { mute: string; unmute: string; }
+};
+```
+
+- `showVolumeText` - Possibility to display the current volume level in UI (default: `false`).
+- `animationTimeInMs` - Duration of fade in/fade out animation (default: `200`).
+- `icons` - Icon names for muted and unmuted state (default: `icons: { muted: 'muted'; unmuted: 'unmuted'; }`).
+
+### Controls
+
+Key codes for volume manipulation:
+
+- `VOL_UP` - Increase volume.
+- `VOL_DOWN` - Decrease volume.
+- `MUTE` - Mute/unmute volume.
+
+## Volume Control UI
+
+Graphical representation of Volume Control. This package contains its own default volume control UI implementation.
+If you want to implement a custom UI, this UI component must implement the [IVolumeControlUI](./src/IVolumeControlUI.ts) interface.
+
+```ts
+export interface IVolumeControlUI {
+    onUpdateVolume: (volumeLevel: number) => void;
+    onUpdateMute: (isMuted: boolean) => void;
+    show: () => void;
+    hide: () => void;
+    isVisible: () => boolean;
+}
+```

package/packages/volume-control/src/IVolumeControlUI.ts

@@ -0,0 +1,26 @@
+export interface IVolumeControlUI {
+    /**
+     * Function that is performed when the volume level is changed.
+     * @param volumeLevel Desired volume state between 0 and 100, 100 is the
+     * highest volume, 0 is quiet
+     */
+    onUpdateVolume: (volumeLevel: number) => void;
+    /**
+     * Function that is performed when the mute state is changed.
+     * @param isMuted Current mute state
+     */
+    onUpdateMute: (isMuted: boolean) => void;
+    /**
+     * Function for showing the VolumeControlUI.
+     */
+    show: () => void;
+    /**
+     * Function for hiding the VolumeControlUI.
+     */
+    hide: () => void;
+    /**
+     * Returns visibility state of the VolumeControlUI.
+     * @returns true if is visible, false otherwise
+     */
+    isVisible: () => boolean;
+}

package/packages/volume-control/src/VolumeControlService.tsx

@@ -0,0 +1,110 @@
+import { Component, createRef, DeclareProps, Reference } from '@24i/bigscreen-sdk/jsx';
+import { device } from '@24i/bigscreen-sdk/device';
+import { switchByKey } from '@24i/bigscreen-sdk/device/keymap';
+import { createTimeout } from '@24i/bigscreen-sdk/utils/timers';
+import { IVolumeControlUI } from './IVolumeControlUI';
+
+const MIN_VOLUME_LEVEL = 0;
+const MAX_VOLUME_LEVEL = 100;
+
+type Props = {
+    volumeStep?: number;
+    displayTimeInMs?: number;
+    volumeControlUI: (ref: Reference) => JSX.Element;
+};
+
+export class VolumeControlService extends Component<Props> {
+    volumeControlUiRef = createRef<IVolumeControlUI>();
+
+    displayTimer = createTimeout();
+
+    volumeLevel = 0;
+
+    isMuted = false;
+
+    static defaultProps = {
+        volumeStep: 10,
+        displayTimeInMs: 3000,
+    };
+
+    declare props: DeclareProps<Props, typeof VolumeControlService.defaultProps>;
+
+    async componentDidMount() {
+        this.volumeLevel = await device.getVolume();
+        this.isMuted = await device.isMute();
+        // render initial mute state and volume
+        this.volumeControlUiRef.current!.onUpdateMute(this.isMuted);
+        this.volumeControlUiRef.current!.onUpdateVolume(this.volumeLevel);
+        this.addGlobalKeyListener();
+    }
+
+    componentWillUnmount() {
+        this.removeGlobalKeyListener();
+        this.displayTimer.clear();
+    }
+
+    onGlobalKeyDown = (event: KeyboardEvent) => {
+        switchByKey(event, {
+            VOL_UP: this.onVolumeUp,
+            VOL_DOWN: this.onVolumeDown,
+            MUTE: this.onMute,
+        });
+    };
+
+    onVolumeUp = () => {
+        const { volumeStep } = this.props;
+        if (this.isMuted) this.toggleMute();
+        const newVolumeLevel = this.volumeLevel + volumeStep;
+        const validatedVolumeLevel = newVolumeLevel < MAX_VOLUME_LEVEL
+            ? newVolumeLevel : MAX_VOLUME_LEVEL;
+        this.updateVolume(validatedVolumeLevel);
+    };
+
+    onVolumeDown = () => {
+        const { volumeStep } = this.props;
+        if (this.isMuted) this.toggleMute();
+        const newVolumeLevel = this.volumeLevel - volumeStep;
+        const validatedVolumeLevel = newVolumeLevel > MIN_VOLUME_LEVEL
+            ? newVolumeLevel : MIN_VOLUME_LEVEL;
+        this.updateVolume(validatedVolumeLevel);
+    };
+
+    onMute = () => {
+        this.toggleMute();
+    };
+
+    toggleMute() {
+        const isMuted = !this.isMuted;
+        device.mute(isMuted);
+        this.volumeControlUiRef.current!.onUpdateMute(isMuted);
+        this.isMuted = isMuted;
+        this.showVolumeControl();
+    }
+
+    updateVolume(volumeLevel: number) {
+        device.setVolume(volumeLevel);
+        this.volumeControlUiRef.current!.onUpdateVolume(volumeLevel);
+        this.volumeLevel = volumeLevel;
+        this.showVolumeControl();
+    }
+
+    showVolumeControl() {
+        const { displayTimeInMs } = this.props;
+        const volumeControlUiRef = this.volumeControlUiRef.current!;
+        if (!volumeControlUiRef.isVisible()) volumeControlUiRef.show();
+        this.displayTimer.set(volumeControlUiRef.hide, displayTimeInMs);
+    }
+
+    addGlobalKeyListener() {
+        window.document.addEventListener('keydown', this.onGlobalKeyDown);
+    }
+
+    removeGlobalKeyListener() {
+        window.document.removeEventListener('keydown', this.onGlobalKeyDown);
+    }
+
+    render() {
+        const { volumeControlUI } = this.props;
+        return volumeControlUI(this.volumeControlUiRef);
+    }
+}

package/packages/volume-control/src/VolumeControlUI/VisualController.animated.ts

@@ -0,0 +1,28 @@
+import { AnimationUtils, JSAnimations } from '@24i/bigscreen-sdk/animations';
+import { VisualControllerBase } from './VisualControllerBase';
+
+export class VisualController extends VisualControllerBase {
+    animation = new JSAnimations();
+
+    onFrame = (value: number) => {
+        this.volumeControlRef.current!.style.opacity = value.toString();
+    };
+
+    onFrameHide = (value: number) => {
+        this.onFrame(value);
+        if (value === 0) super.hide();
+    };
+
+    show() {
+        super.show();
+        this.animation.start(
+            0, 1, this.animationTimeInMs, AnimationUtils.ease,
+        ).onFrame(this.onFrame);
+    }
+
+    hide() {
+        this.animation.start(
+            1, 0, this.animationTimeInMs, AnimationUtils.ease,
+        ).onFrame(this.onFrameHide);
+    }
+}

package/packages/volume-control/src/VolumeControlUI/VisualController.ts

@@ -0,0 +1,3 @@
+import { VisualControllerBase } from './VisualControllerBase';
+
+export class VisualController extends VisualControllerBase {}

package/packages/volume-control/src/VolumeControlUI/VisualControllerBase.ts

@@ -0,0 +1,26 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { getDisplayToggler } from '@24i/bigscreen-sdk/utils/displayToggler';
+
+export abstract class VisualControllerBase {
+    volumeControlRef = createRef<HTMLDivElement>();
+
+    displayToggler = getDisplayToggler(this.volumeControlRef, true);
+
+    animationTimeInMs: number;
+
+    constructor(animationTimeInMs: number) {
+        this.animationTimeInMs = animationTimeInMs;
+    }
+
+    show() {
+        this.displayToggler.show();
+    }
+
+    hide() {
+        this.displayToggler.hide();
+    }
+
+    isVisible() {
+        return this.displayToggler.isVisible();
+    }
+}

package/packages/volume-control/src/VolumeControlUI/VolumeControl.scss

@@ -0,0 +1,18 @@
+.volume-control {
+    position: absolute;
+    z-index: 700;
+
+    >.volume-track {
+        position: relative;
+
+        >.volume-level {
+            position: absolute;
+            bottom: 0;
+            width: 100%;
+        }
+    }
+
+    >.icon {
+        position: relative;
+    }
+}

package/packages/volume-control/src/VolumeControlUI/VolumeControl.styles.animated.scss

@@ -0,0 +1,2 @@
+@import './VolumeControl';
+@import './animated';

package/packages/volume-control/src/VolumeControlUI/VolumeControl.styles.scss

@@ -0,0 +1 @@
+@import './VolumeControl';

package/packages/volume-control/src/VolumeControlUI/VolumeControlUI.tsx

@@ -0,0 +1,80 @@
+import { Component, createRef, DeclareProps, setText } from '@24i/bigscreen-sdk/jsx';
+import { Icon } from '@24i/bigscreen-sdk/icon';
+import { DISPLAY_NONE } from '@24i/bigscreen-sdk/utils';
+import { IVolumeControlUI } from '../IVolumeControlUI';
+import { VisualControllerBase } from './VisualControllerBase';
+import { VisualController } from './VisualController';
+
+import './VolumeControl.styles';
+
+type Props = {
+    showVolumeText?: boolean;
+    animationTimeInMs?: number;
+    icons?: { muted: string; unmuted: string; };
+};
+
+export class VolumeControlUI extends Component<Props> implements IVolumeControlUI {
+    visualController: VisualControllerBase;
+
+    volumeLevelRef = createRef<HTMLDivElement>();
+
+    volumeTextRef = createRef<HTMLDivElement>();
+
+    muteIconRef = createRef<Icon<any>>();
+
+    static defaultProps = {
+        showVolumeText: false,
+        animationTimeInMs: 200,
+        icons: { muted: 'muted', unmuted: 'unmuted' },
+    };
+
+    declare props: DeclareProps<Props, typeof VolumeControlUI.defaultProps>;
+
+    constructor(props: Props) {
+        super(props);
+        const { animationTimeInMs } = this.props;
+        this.visualController = new VisualController(animationTimeInMs);
+    }
+
+    onUpdateVolume(volumeLevel: number) {
+        this.volumeLevelRef.current!.style.height = `${volumeLevel}%`;
+        if (this.volumeTextRef.current) setText(this.volumeTextRef, volumeLevel.toString());
+    }
+
+    onUpdateMute(isMuted: boolean) {
+        const { icons: { muted, unmuted } } = this.props;
+        if (isMuted) {
+            this.muteIconRef.current!.setIcon(muted);
+        } else {
+            this.muteIconRef.current!.setIcon(unmuted);
+        }
+    }
+
+    show = () => {
+        this.visualController.show();
+    };
+
+    hide = () => {
+        this.visualController.hide();
+    };
+
+    isVisible() {
+        return this.visualController.isVisible();
+    }
+
+    render() {
+        const { showVolumeText } = this.props;
+        return (
+            <div
+                className={`volume-control ${DISPLAY_NONE}`}
+                ref={this.visualController.volumeControlRef}
+            >
+                <div className="volume-track">
+                    <div className="volume-level" ref={this.volumeLevelRef} />
+                </div>
+                { showVolumeText && <div className="volume-number" ref={this.volumeTextRef} /> }
+                <Icon ref={this.muteIconRef} />
+            </div>
+        );
+    }
+}

package/packages/volume-control/src/VolumeControlUI/_animated.scss

@@ -0,0 +1,8 @@
+@import '@24i/bigscreen-sdk/sass-utils/transition';
+@import '@24i/bigscreen-sdk/sass-utils/prefix-property';
+
+.volume-control {
+    .volume-level {
+        @include transition(prefix-property(height), 300ms);
+    }
+}

package/packages/volume-control/src/VolumeControlUI/index.ts

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

package/packages/volume-control/src/index.ts

@@ -0,0 +1,2 @@
+export { VolumeControlService } from './VolumeControlService';
+export { VolumeControlUI } from './VolumeControlUI';

package/packages/zapping/README.md

@@ -0,0 +1,88 @@
+---
+id: README
+title: Zapping
+hide_title: true
+sidebar_label: Zapping
+---
+
+# Zapping
+Zapping package is higher level component over [NumericZapper](../numeric-zapper/README.md).
+- Numeric zapper returns a number for numeric zapping.
+- **Zapping returns a channel for numeric zapping as well as CHANNEL UP/DOWN zapping.**
+
+## Props\<T extends Asset = Asset\>
+- channels - an array of all channels
+- currentChannel - current channel at the point of render
+- onZappedToChannel - required callback for when the channel should change
+- onZappedToInvalidChannelNumber - optional callback to handle invalid channel number (e.g. show toast)
+- numericZapper - optional [NumericZapper Props](../numeric-zapper/README.md#props). If they are passed,
+then the `Zapping` will render `NumericZapper` with these. If omitted, then `Zapping` will try to use
+`numericZapperService` reference.
+- channelUpDownZapping - optional configuration for CHANNEL UP/DOWN zapping. If omitted CHANNEL UP/DOWN
+zapping will not be used.
+- - onProposedChannelChange - optional callback for immediate UI changes with pressing CHANNEL UP/DOWN.
+- - safeTimeoutMs - timeout between the last CHANNEL UP/DOWN press and calling `onZappedToChannel`.
+Defaults to 800ms.
+
+## Use example
+```tsx
+class LivePlayer extends Component<Props> implements IRoute<RouteParams> {
+    uiWrap = createRef<HTMLDivElement>();
+
+    livePlayerUI = createRef<LivePlayerUI>();
+        
+    onZappedToChannel = (channel: Asset) => {
+        go(`/live-player/${channel.id}`);
+    };
+
+    onZappedToInvalidChannelNumber = (channelNumber: number) => {
+        showToast(`There is no channel with number '${channelNumber}'.`);
+    };
+
+    onProposedChannelChange = (channel: Asset) => {
+        this.livePlayerUI.current!.updateChannel(channel);
+    };
+
+    activate(routeParams: RouteParams) {
+        this.initPlayer(routeParams);
+    }
+
+    reactivate(routeParams: RouteParams) {
+        this.initPlayer(routeParams);
+    }
+
+    async initPlayer({ channelId }: RouteParams) {
+        const { dataProvider } = this.props;
+        const { channels } = await dataProvider();
+        const currentChannel = find(channels, ({ id }) => id === channelId);
+        // Initialize player - this.player.init()
+        this.renderUI(channels, currentChannel);
+    }
+
+    renderUI(channels: Asset[], currentChannel: Asset) {
+        this.clearMount((
+            <>
+                <Zapping
+                    channels={channels}
+                    currentChannel={currentChannel}
+                    onZappedToChannel={this.onZappedToChannel}
+                    onZappedToInvalidChannelNumber={this.onZappedToInvalidChannelNumber}
+                    channelUpDownZapping={{
+                        onProposedChannelChange: this.onProposedChannelChange,
+                    }}
+                />
+                <LivePlayerUI ref={this.livePlayerUI} currentChannel={currentChannel} />
+            </>
+        ), this.uiWrap);
+    }
+
+    render() {
+        return (
+            <div className="scene live-player" data-zapper-allowed>
+                <div className="video-container" />
+                <div className="ui-wrap" ref={this.uiWrap} />
+            </div>
+        )
+    }
+}
+```

package/packages/zapping/src/ChannelZapping.ts

@@ -0,0 +1,134 @@
+import { CHANNEL_UP, CHANNEL_DOWN } from '@24i/bigscreen-sdk/device/keymap';
+import { zapperServiceRef } from '@24i/bigscreen-sdk/numeric-zapper';
+import { stopEvent } from '@24i/bigscreen-sdk/utils/stopEvent';
+import { createTimeout } from '@24i/bigscreen-sdk/utils/timers';
+import { findIndex } from '@24i/bigscreen-sdk/perf-utils/array';
+import { noop } from '@24i/bigscreen-sdk/utils/noop';
+import { Asset } from '@24i/smartapps-datalayer/models';
+
+const Direction = {
+    UP: 1,
+    DOWN: -1,
+} as const;
+
+/**
+ * **ChannelZapping Props**
+ *
+ * - onChannelChange - required callback called with the channel to change to
+ * - onProposedChannelChange - optional callback for immediate UI update
+ * - safeTimeoutMs - delay between CH_UP/CH_DOWN press and onChannelChange callback (default: 800ms)
+ */
+export type Props<T extends Asset = Asset> = {
+    onChannelChange: (channel: T) => void,
+    onProposedChannelChange?: (channel: T) => void,
+    safeTimeoutMs?: number,
+};
+
+const SAFE_TIMEOUT = 800;
+
+/**
+ * Finds and returns the index of current channel in all channels.
+ * @param channels the array of all channels
+ * @param currentChannel currently active channel
+ * @returns index of current channel in the array of all channels
+ */
+const getCurrentChannelIndex = (channels: Asset[], currentChannel: Asset) => (
+    findIndex(channels, (channel) => channel.id === currentChannel.id)
+);
+
+/**
+ * **Channel Zapping**
+ *
+ * Controlling module for zapping with CHANNEL_UP and CHANNEL_DOWN keys.
+ */
+export class ChannelZapping<T extends Asset = Asset> {
+    /**
+     * Array of all channels.
+     */
+    channels: T[];
+
+    /**
+     * Index of the current channel.
+     */
+    currentIndex: number;
+
+    /**
+     * Safe timeout to delay zapping and allow more CHANNEL_UP/CHANNEL_DOWN presses.
+     */
+    safeTimeout = createTimeout();
+
+    /**
+     * Time in ms between CH_UP/CH_DOWN press and onChannelChange callback.
+     */
+    safeTimeoutMs: number;
+
+    /**
+     * Callback with currently selected channel for immediate UI updates.
+     */
+    onProposedChannelChange: (channel: T) => void = noop;
+
+    /**
+     * Callback for definitive channel change.
+     */
+    onChannelChange: (channel: T) => void;
+
+    constructor(
+        channels: T[],
+        currentChannel: T,
+        props: Props<T>,
+    ) {
+        const { onChannelChange, onProposedChannelChange, safeTimeoutMs } = props;
+        this.channels = channels;
+        this.currentIndex = getCurrentChannelIndex(channels, currentChannel);
+        this.onChannelChange = onChannelChange;
+        if (onProposedChannelChange) {
+            this.onProposedChannelChange = onProposedChannelChange;
+        }
+        this.safeTimeoutMs = safeTimeoutMs ?? SAFE_TIMEOUT;
+    }
+
+    /**
+     * Handles CHANNEL_UP and CHANNEL_DOWN buttons.
+     * @param event keyboard even
+     */
+    onKeyDown(event: KeyboardEvent) {
+        const isUp = CHANNEL_UP.is(event);
+        if (isUp || CHANNEL_DOWN.is(event)) {
+            this.changeChannel(isUp ? Direction.UP : Direction.DOWN);
+            stopEvent(event);
+        }
+    }
+
+    /**
+     * Changes to the next/previous channel.
+     * @param direction direction of the change
+     */
+    private changeChannel(direction: number) {
+        zapperServiceRef.current!.resetZapper();
+        const newChannel = this.getChannel(direction);
+        this.onProposedChannelChange(newChannel);
+        this.safeTimeout.set(this.confirmChannelChange(newChannel), SAFE_TIMEOUT);
+    }
+
+    /**
+     * Returns next channel in the given direction (cyclically).
+     * @param direction direction in which to move
+     * @returns channel object in the given direction
+     */
+    private getChannel(direction: number) {
+        this.currentIndex += direction;
+        const { length } = this.channels;
+        if (this.currentIndex < 0) this.currentIndex = length - 1;
+        else if (this.currentIndex >= length) this.currentIndex = 0;
+        return this.channels[this.currentIndex];
+    }
+
+    /**
+     * Finishes the channel change (after {@link ChannelZapping.safeTimeout safeTimeout}).
+     * @param channel channel on which to change
+     * @returns function that actually does the change for safeTimeout callback
+     */
+    private readonly confirmChannelChange = (channel: T) => () => {
+        this.onChannelChange(channel);
+    };
+}