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

package/packages/mouse-navigation/src/__test__/MouseElementWrapper.spec.tsx

@@ -0,0 +1,61 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { getKeyMap } from '@24i/bigscreen-sdk/device';
+import { MountedComponent, shallow, keydown } from '@24i/bigscreen-sdk/jsx/test-utils';
+import { MouseElementWrapper } from '../MouseElementWrapper';
+import { MouseNavigationInterface } from '../MouseNavigationInterface';
+
+describe('MouseElementWrapper', () => {
+    const mPointRef = createRef<HTMLDivElement>();
+    let root: MountedComponent<HTMLDivElement>;
+    let nav: MountedComponent<MouseElementWrapper>;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        root = shallow(<div className="mounting-point" ref={mPointRef} />);
+        nav = shallow(
+            <>
+                <MouseElementWrapper
+                    getMountingPoint={() => mPointRef}
+                >
+                    <div className="test-child" />
+                </MouseElementWrapper>
+            </>,
+        );
+    });
+
+    afterEach(() => {
+        nav.unmount();
+        root.unmount();
+    });
+
+    it('should not render child immediately', () => {
+        expect(root.find('.test-child')).toBe(null);
+    });
+
+    it('should handle key event correctly', () => {
+
+        const event = new MouseEvent('mousemove', {});
+        document.dispatchEvent(event);
+
+        expect(root.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().domRef.current);
+
+        keydown(document, getKeyMap().UP!);
+        expect(root.find('.mounting-point').firstElementChild).toBe(null);
+    });
+
+    it('should handle interface request to hide', () => {
+        const event = new MouseEvent('mousemove', {});
+        document.dispatchEvent(event);
+
+        expect(root.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().domRef.current);
+
+        MouseNavigationInterface.hide();
+        expect(root.find('.mounting-point').firstElementChild).toBe(null);
+
+        MouseNavigationInterface.show();
+        expect(root.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().domRef.current);
+    });
+});

package/packages/mouse-navigation/src/__test__/MouseNavigation.spec.tsx

@@ -0,0 +1,107 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { getKeyMap } from '@24i/bigscreen-sdk/device';
+import { MountedComponent, shallow, keydown } from '@24i/bigscreen-sdk/jsx/test-utils';
+import { MouseNavigation } from '../MouseNavigation';
+import { MouseNavigationInterface } from '../MouseNavigationInterface';
+
+const forwardMock = jest.fn();
+const backwardMock = jest.fn();
+const showForwardMock = jest.fn(() => true);
+const showBackwardMock = jest.fn(() => true);
+
+describe('MouseNavigation', () => {
+    const mPointRef = createRef<HTMLDivElement>();
+    let nav: MountedComponent<MouseNavigation>;
+
+    beforeEach(() => {
+        nav = shallow(
+            <MouseNavigation
+                getMountingPoint={() => mPointRef}
+                direction="vertical"
+                forward={forwardMock}
+                backward={backwardMock}
+                shouldShowMrcuForward={showForwardMock}
+                shouldShowMrcuBackward={showBackwardMock}
+            >
+                <>
+                    <div className="test-child" />
+                    <div className="mounting-point" ref={mPointRef} />
+                </>
+            </MouseNavigation>,
+        );
+    });
+
+    afterEach(() => {
+        nav.unmount();
+    });
+
+    it('should handle key event correctly', () => {
+
+        const event = new MouseEvent('mousemove', {});
+        document.dispatchEvent(event);
+
+        expect(nav.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().arrows.current?.domRef.current);
+
+        keydown(document, getKeyMap().UP!);
+
+        expect(nav.find('.mounting-point').firstElementChild).toBe(null);
+    });
+
+    it('should render child', () => {
+        expect(nav.find('.test-child').className).not.toBe(null);
+    });
+
+    it('should return correct mapped direction', () => {
+        expect(nav.ref().mapDirectionToProps('horizontal').horizontal).toBe(true);
+        expect(nav.ref().mapDirectionToProps('vertical').vertical).toBe(true);
+    });
+
+    it('should handle interface request to hide', () => {
+        const event = new MouseEvent('mousemove', {});
+        document.dispatchEvent(event);
+
+        expect(nav.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().arrows.current?.domRef.current);
+
+        MouseNavigationInterface.hide();
+
+        expect(nav.find('.mounting-point').firstElementChild).toBe(null);
+
+        MouseNavigationInterface.show();
+
+        expect(nav.find('.mounting-point').firstElementChild)
+            .toBe(nav.ref().arrows.current?.domRef.current);
+    });
+
+    it('should propagate forward and backward', () => {
+        nav.ref().handleArrowState = jest.fn();
+        nav.ref().forward();
+        nav.ref().backward();
+
+        expect(forwardMock).toHaveBeenCalledTimes(1);
+        expect(backwardMock).toHaveBeenCalledTimes(1);
+        expect(nav.ref().handleArrowState).toHaveBeenCalledTimes(2);
+    });
+
+    it('should show/hide arrows as reported', () => {
+        nav.ref().arrows = {
+            current: {
+                enableArrow: jest.fn(),
+                disableArrow: jest.fn(),
+            },
+        } as any;
+
+        nav.ref().handleArrowState();
+        expect(nav.ref().arrows.current?.enableArrow).toHaveBeenNthCalledWith(1, 'down');
+        expect(nav.ref().arrows.current?.enableArrow).toHaveBeenNthCalledWith(2, 'up');
+        expect(nav.ref().arrows.current?.enableArrow).toHaveBeenCalledTimes(2);
+
+        showForwardMock.mockImplementationOnce(() => false);
+        showBackwardMock.mockImplementationOnce(() => false);
+        nav.ref().handleArrowState();
+        expect(nav.ref().arrows.current?.disableArrow).toHaveBeenNthCalledWith(1, 'down');
+        expect(nav.ref().arrows.current?.disableArrow).toHaveBeenNthCalledWith(2, 'up');
+        expect(nav.ref().arrows.current?.disableArrow).toHaveBeenCalledTimes(2);
+    });
+});

package/packages/mouse-navigation/src/index.ts

@@ -0,0 +1,3 @@
+export { MouseElementWrapper } from './MouseElementWrapper';
+export { MouseNavigation } from './MouseNavigation';
+export { MouseNavigationInterface } from './MouseNavigationInterface';

package/packages/numeric-zapper/README.md

@@ -0,0 +1,153 @@
+---
+id: README
+title: Numeric Zapper
+hide_title: true
+sidebar_label: Numeric Zapper
+---
+
+# Numeric Zapper
+Numeric Zapper provides a way to show zapper component to the user, for example when trying to change the channel, or position in the EPG.
+It provides component and service that exposes the needed methods for interaction and control.
+
+## Supported Features
+- Can be used either with or without the ZapperService
+- ZapperService provides the API for interaction and control of the Numeric Zapper
+- The component can be either disabled or enabled based on your wish
+- Zapping can be allowed only on specific wrapper elements
+- Default callback can be set to be used in case there is no other specified
+- Can pass specific callback (e.g. when going from Live TV to EPG), to change the behavior of the zapper
+- Can set custom placeholder with prop `placeholderChar` - defaults to `-`
+- Can hide placeholders with prop `noPlaceholders` - defaults to false
+
+## Basic Usage
+```jsx
+<NumericZapper
+    ref={reference}
+    className="sample-numeric-zapper"
+    enabled
+    onSubmit={(num: number) => {
+        console.log('You are trying to zap to: ', num);
+    }}
+    visibleOnEnable={false}
+    timeout={3000}
+/>
+```
+
+NumericZapper will not work by default, you need to allow it on specific areas, where you want to have zapping functional.
+See usage below for mode details.
+
+### Styles
+The Numeric Zapper component comes with created styles that can be used freely. To use them, simply import the styles from the package.
+```jsx
+import '@24i/bigscreen-sdk/numeric-zapper/styles';
+```
+
+## Props
+All of the Props that the NumericZapper consumes are optional
+
+```jsx
+type Props = {
+    className?: string,
+    enabled?: boolean;
+    onSubmit?: ZapFunction,
+    visibleOnEnable?: boolean,
+    timeout?: boolean,
+};
+```
+
+- `className` is set alongside the default className ("numeric-zapper")
+- `enabled` (_if not specified, default value is `false`_) indicates whether or the zapper is enabled. While disabled, NumericZapper does not catch any key event.
+- `onSubmit` is a function that is called upon completing the 'zapper' (either by timeout or by `[enter]` key
+- `visibleOnEnable` (_if not specified, default value is `false`_) tells the component if it should be visible with no numbers displaying - - - - at the moment when when zapper is enabled.
+- `timeout` (_if not specified, default value is `2000`_) is the time (in ms) the component should wait before firing the Zap function
+
+
+### ZapFunction:
+Is a simple function, that takes a number as a parameter and does not return anything.
+
+```jsx
+type ZapFunction = (zap: number) => void;
+```
+
+## ZapperService
+ZapperService is a service that exposes a few of the methods essential for control of the NumericZapper.
+
+```jsx
+export type ZapperInterface = {
+    enable: (callback?: ZapFunction, isDefault?: boolean) => void,
+    disable: () => void,
+    isEnabled: () => boolean,
+};
+```
+
+- `enable` takes two possible arguments, first being ZapFunction - if you don't have default ZapFunction already defined, this parameter is mandatory. Second is telling the function if the ZapFunction should be stored as defaultZapperFunction or specificZapperFunction
+- `disable` disables the NumericZapper and removes the `Specific Zap Function`.
+- `isEnabled` says if the component is enabled
+
+### Usage
+First you need to pass the reference to the NumericZapper to zapperServiceRef. To do that, you need to render the component somewhere (it can be in the root, in the one specific scene, etc.). Then you need to pass the reference as described below.
+
+```jsx
+import {
+    NumericZapper,
+    zapperServiceRef,
+} from '@24i/bigscreen-sdk/numeric-zapper';
+
+...
+
+render() {
+  return (
+      <NumericZapper ref={zapperServiceRef} />
+  );
+}
+```
+
+The next step is to import the ZapperService and start using it. This can be done basically anywhere in the app (as long as the component is rendered) since the service holds the reference to it.
+
+```jsx
+import { getZapperService } from '@24i/bigscreen-sdk/numeric-zapper';
+
+const zapperService = getZapperService();
+zapperService.enable((num: number) => {
+  zapToChannel(num);
+});
+```
+
+In the last step, you need to allow zapper in specific area. It does not work everywhere by default.
+Zapper is working only when current focused element is wrapped by some other
+element (anywhere below it in the DOM tree) with special dataset parameter `data-zapper-allowed="true"`.
+On the other hand, when you add dataset parameter `data-zapper-allowed="false"` to the wrapper element,
+zapper will not work, when focus is on one of its children.
+These conditions also work when dataset parameter is on focused element itself.
+
+### Examples
+```tsx
+// zapper is allowed to work in the whole program-guide scene
+// but does not work when the focus is on the ProgramInfo component
+<div
+    className="scene program-guide"
+    ref={this.domRef}
+    data-zapper-allowed="true"
+>
+    ...
+    <div data-zapper-allowed="false">
+        <ProgramInfo ref={this.programInfoRef}/>
+    </div>
+</div>
+```
+
+You can use also `data-zapper-allowed` property like this:
+
+```tsx
+<div data-zapper-allowed>
+    ...
+</div>
+
+<div data-zapper-allowed={true}>
+    ...
+</div>
+
+<div data-zapper-allowed={false}>
+    ...
+</div>
+```

package/packages/numeric-zapper/src/NumericZapper.scss

@@ -0,0 +1,20 @@
+.numeric-zapper {
+    border-radius: 6px;
+    font-size: $zapper-font-size;
+    height: $zapper-height;
+    left: $zapper-left;
+    line-height: $zapper-height;
+    position: absolute;
+    top: $zapper-top;
+    width: $zapper-width;
+    z-index: 700;
+    text-align: center;
+    outline: none;
+    background-color: #4c4c4c;
+
+    .zapper-number {
+        display: inline-block;
+        text-align: center;
+        width: $zapper-number-width;
+    }
+}

package/packages/numeric-zapper/src/NumericZapper.styles.1080.scss

@@ -0,0 +1,2 @@
+@import './sizes.1080';
+@import './NumericZapper';

package/packages/numeric-zapper/src/NumericZapper.styles.scss

@@ -0,0 +1,2 @@
+@import './sizes';
+@import './NumericZapper';

package/packages/numeric-zapper/src/NumericZapper.tsx

@@ -0,0 +1,256 @@
+import {
+    createRef,
+    Component,
+    setText,
+    DeclareProps,
+    Reference,
+} from '@24i/bigscreen-sdk/jsx';
+import { getKeyDigit } from '@24i/bigscreen-sdk/device';
+import { BACK, ENTER } from '@24i/bigscreen-sdk/device/keymap';
+import { map } from '@24i/bigscreen-sdk/perf-utils/array';
+import { nTimes } from '@24i/bigscreen-sdk/utils/nTimes';
+import { stopEvent } from '@24i/bigscreen-sdk/utils/stopEvent';
+import {
+    setActiveElementAsFocusCandidate, focusCandidate,
+} from '@24i/bigscreen-sdk/focus';
+import {
+    getDisplayToggler,
+    DISPLAY_NONE,
+} from '@24i/bigscreen-sdk/utils/displayToggler';
+import { noop } from '@24i/bigscreen-sdk/utils/noop';
+import { createTimeout } from '@24i/bigscreen-sdk/utils/timers';
+import { isZapperAllowed } from './ZapperAllower';
+
+type ZapFunction = (zap: number) => void;
+
+export type Props = {
+    className?: string,
+    enabled?: boolean;
+    onSubmit?: ZapFunction,
+    visibleOnEnable?: boolean,
+    timeout?: number,
+    placeholderChar?: string,
+    noPlaceholders?: boolean,
+};
+type SubmitZap = {
+    defaultZap: ZapFunction | undefined;
+    specificZap: ZapFunction | undefined;
+};
+
+const MAX_DIGITS = 4;
+
+export type ZapperInterface = {
+    enable: (callback?: ZapFunction, isDefault?: boolean) => void,
+    disable: () => void,
+    isEnabled: () => boolean,
+};
+
+export class NumericZapper extends Component<Props> {
+    div = createRef<HTMLDivElement>();
+
+    zapperNumbers: number[] = [];
+
+    waitingTimeout = createTimeout();
+
+    submit: SubmitZap = {
+        defaultZap: undefined,
+        specificZap: undefined,
+    };
+
+    isZapping = false;
+
+    isZapperEnabled = false;
+
+    displayToggler = getDisplayToggler(this.div, true);
+
+    charWrappers: Reference<HTMLDivElement>[] = nTimes(MAX_DIGITS, () => createRef());
+
+    charDisplayTogglers = map(this.charWrappers, (wrapper) => (
+        // eslint-disable-next-line react/destructuring-assignment
+        getDisplayToggler(wrapper, this.props.noPlaceholders)
+    ));
+
+    static defaultProps = {
+        className: '',
+        timeout: 2000,
+        enabled: false,
+        visibleOnEnable: false,
+        onSubmit: noop,
+        placeholderChar: '-',
+        noPlaceholders: false,
+    };
+
+    declare props: DeclareProps<Props, typeof NumericZapper.defaultProps>;
+
+    componentDidMount() {
+        const { enabled, onSubmit, visibleOnEnable } = this.props;
+        if (onSubmit) this.submit.defaultZap = onSubmit;
+        if (enabled) {
+            this.registerKeyHandler();
+            if (visibleOnEnable) this.showAndFocus();
+        }
+    }
+
+    componentWillUnmount() {
+        this.unregisterKeyHandler();
+        if (this.submit.specificZap) this.submit.specificZap = undefined;
+    }
+
+    getZapperInterface = (): ZapperInterface => ({
+        enable: this.enable,
+        disable: this.disable,
+        isEnabled: this.isEnabled,
+    });
+
+    isEnabled = () => this.isZapperEnabled;
+
+    enable = (callback?: (zap: number) => void, defaultSubmit = false) => {
+        if (callback) {
+            if (!defaultSubmit) this.submit.specificZap = callback;
+            else this.submit.defaultZap = callback;
+        }
+        this.isZapperEnabled = true;
+        this.registerKeyHandler();
+        const { visibleOnEnable } = this.props;
+        if (visibleOnEnable) {
+            this.showAndFocus();
+        }
+    };
+
+    disable = () => {
+        this.submit.specificZap = undefined;
+        this.isZapperEnabled = false;
+        this.unregisterKeyHandler();
+        this.resetZapper();
+    };
+
+    onGlobalKeyDown = (event: KeyboardEvent) => {
+        const digit = getKeyDigit(event);
+        if (digit !== undefined) {
+            this.processDigit(digit);
+        } else if (this.isZapping) {
+            if (isZapperAllowed()) {
+                if (BACK.is(event) && this.zapperNumbers.length !== 0) {
+                    this.resetZapper();
+                    stopEvent(event);
+                } else if (ENTER.is(event)) {
+                    this.submitZapAndResetZapper();
+                    stopEvent(event);
+                }
+            } else {
+                this.resetZapper();
+            }
+        }
+    };
+
+    processDigit(digit: number) {
+        if (isZapperAllowed()) {
+            if (!this.isZapping) {
+                this.isZapping = true;
+                this.showAndFocus();
+            }
+            this.updateData(digit);
+        } else if (this.isZapping) {
+            this.resetZapper();
+        }
+    }
+
+    registerKeyHandler() {
+        window.addEventListener('keydown', this.onGlobalKeyDown, true);
+    }
+
+    unregisterKeyHandler() {
+        window.removeEventListener('keydown', this.onGlobalKeyDown, true);
+    }
+
+    resetZapper(doNotHide = false) {
+        this.isZapping = false;
+        this.stopWaitingTimeout();
+        if (!doNotHide) this.hideAndBlur();
+
+        const { placeholderChar, noPlaceholders } = this.props;
+        const children = this.div.current!.childNodes;
+        for (let i = 0; i < children.length; i++) {
+            setText(children[i] as HTMLElement, placeholderChar);
+            if (noPlaceholders) this.charDisplayTogglers[i].hide();
+        }
+
+        this.zapperNumbers = [];
+    }
+
+    submitZapAndResetZapper() {
+        const { zapperNumbers } = this;
+
+        this.resetZapper();
+
+        if (!isZapperAllowed()) return;
+
+        const zapNumber = parseInt(zapperNumbers.join(''), 10);
+
+        if (this.submit.specificZap) {
+            this.submit.specificZap(zapNumber);
+        } else if (this.submit.defaultZap) {
+            this.submit.defaultZap(zapNumber);
+        }
+    }
+
+    startWaitingTimeout() {
+        const { timeout } = this.props;
+        this.stopWaitingTimeout();
+        this.waitingTimeout.set(() => {
+            this.submitZapAndResetZapper();
+        }, timeout);
+    }
+
+    stopWaitingTimeout() {
+        this.waitingTimeout.clear();
+    }
+
+    updateData(digit: number) {
+        const { noPlaceholders } = this.props;
+        if (this.zapperNumbers.length === MAX_DIGITS) {
+            this.resetZapper(true);
+        }
+        const index = this.zapperNumbers.length;
+        const element = this.div.current!.childNodes[index] as HTMLElement;
+        setText(element, digit.toString());
+        if (noPlaceholders) this.charDisplayTogglers[index].show();
+        this.zapperNumbers.push(digit);
+        this.startWaitingTimeout();
+    }
+
+    showAndFocus() {
+        if (this.displayToggler.isVisible()) return;
+        setActiveElementAsFocusCandidate();
+        this.displayToggler.show();
+        this.div.current!.focus();
+    }
+
+    hideAndBlur() {
+        if (this.displayToggler.isHidden()) return;
+        this.displayToggler.hide();
+        this.div.current!.blur();
+        focusCandidate();
+    }
+
+    render() {
+        const { className, placeholderChar, noPlaceholders } = this.props;
+        return (
+            <div
+                className={`numeric-zapper ${className || ''} ${DISPLAY_NONE}`}
+                ref={this.div}
+                tabIndex={0}
+                data-zapper-allowed
+            >
+                {nTimes(MAX_DIGITS, (_, index) => (
+                    <div
+                        ref={this.charWrappers[index]}
+                        className={`zapper-number ${noPlaceholders ? DISPLAY_NONE : ''}`}
+                    >
+                        {placeholderChar}
+                    </div>
+                ))}
+            </div>
+        );
+    }
+}

package/packages/numeric-zapper/src/ZapperAllower.ts

@@ -0,0 +1,15 @@
+import { isElementWrappedBy } from '@24i/bigscreen-sdk/utils/elementUtils';
+
+export const isZapperAllowed = () => {
+    const focusedElement = document.activeElement as HTMLElement;
+    let isAllowed = false;
+    isElementWrappedBy(focusedElement, (currentWrapper: HTMLElement) => {
+        const { zapperAllowed } = currentWrapper.dataset;
+        if (zapperAllowed !== undefined) {
+            isAllowed = zapperAllowed === 'true';
+            return true;
+        }
+        return false;
+    }, true);
+    return isAllowed;
+};

package/packages/numeric-zapper/src/ZapperService.tsx

@@ -0,0 +1,8 @@
+import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { NumericZapper, ZapperInterface } from './NumericZapper';
+
+export const zapperServiceRef = createRef<NumericZapper>();
+
+export const getZapperService = (): ZapperInterface => (
+    zapperServiceRef.current!.getZapperInterface()
+);

package/packages/numeric-zapper/src/_sizes.1080.scss

@@ -0,0 +1,7 @@
+$zapper-top: 480px;
+$zapper-left: 735px;
+$zapper-height: 120px;
+$zapper-width: 450px;
+
+$zapper-font-size: 63px;
+$zapper-number-width: 72px;

package/packages/numeric-zapper/src/_sizes.scss

@@ -0,0 +1,7 @@
+$zapper-top: 320px;
+$zapper-left: 490px;
+$zapper-height: 80px;
+$zapper-width: 300px;
+
+$zapper-font-size: 42px;
+$zapper-number-width: 48px;

package/packages/numeric-zapper/src/index.ts

@@ -0,0 +1,4 @@
+export { NumericZapper } from './NumericZapper';
+export type { ZapperInterface } from './NumericZapper';
+export { getZapperService, zapperServiceRef } from './ZapperService';
+export { isZapperAllowed } from './ZapperAllower';

package/packages/numeric-zapper/src/interface.ts

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

package/packages/numeric-zapper/src/styles.ts

@@ -0,0 +1 @@
+import './NumericZapper.styles';