@24i/bigscreen-sdk 1.0.3-alpha.2091 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@24i/bigscreen-sdk",
-    "version": "1.0.3-alpha.2091",
+    "version": "1.0.3",
     "description": "SmartApps BIGscreen SDK monorepo",
     "main": "index.js",
     "scripts": {

package/packages/focus/README.md

@@ -8,6 +8,18 @@ sidebar_label: Focus
 # Focus
 This package takes care of focus in SmartApps BIGscreen apps. It contains layout components and modules for handling focus candidates and focus limiting.
 
+## IFocusable
+IFocusable is an interface that should be implemented by anything that can be focused.
+```ts
+interface IFocusable {
+    focus(options?: FocusOptions): void,
+    hasDom?(element: HTMLElement): boolean,
+}
+```
+- focus is the main function that is called when focusing component/element.
+- hasDom is optional optimization for components to help Layout components locate the currently
+focused child.
+
 ## Layout components
 - Vertical: Use it to create focus between elements vertically (up/down)
 - Horizontal: Use it to create focus between elements horizontally (left/right)
@@ -20,9 +32,18 @@ Both of these components share the same props;
 ### Props
 - children: Children will be rendered as is.
 - focusableChildren: Array of references between which the focus moves.
-- domRef: Reference to a dom element that corresponds to closest dom wrapper. It will listen onKeyDown on this element.
-- onFocusChanged: Optional callback after focus has changed. It receives reference to focused element and its index. Ideal place to change other elements (e.g. header changing with focused movie)
-- onBeforeFocusChange: Optional callback just before focus change. It receives reference to focused element and its index. Ideal place for preparing for the change (e.g. moving the container to fit new element in the screen)
+- domRef: Reference to a dom element that corresponds to closest dom wrapper.
+It will listen onKeyDown on this element.
+- onFocusChanged: Optional callback after focus has changed. It receives a reference
+to the focused element and its index. Ideal place to change other elements
+(e.g. header changing with focused movie)
+- onBeforeFocusChange: Optional callback just before focus change. It receives a reference
+to the focused element and its index. Ideal place for preparing for the change
+(e.g. moving the container to fit new element in the screen)
+- dir: Optional forceful setting of the component direction. Defaults to `'auto'` which follows
+the direction of the app.
+`'ltr'` always forces left-to-right layout,
+`'rtl'` always forces right-to-left.
 
 ### Usage
 ```jsx

package/packages/focus/src/IFocusable.ts

@@ -1,3 +1,4 @@
 export interface IFocusable {
-    focus: (options?: FocusOptions) => void,
+    focus(options?: FocusOptions): void,
+    hasDom?(element: HTMLElement): boolean,
 }

package/packages/focus/src/Layout/Base.tsx

@@ -9,6 +9,7 @@ export type Props = SharedProps & {
     focusableChildren: Array<Reference>,
     onFocusChanged?: (focused: Reference, index: number) => any,
     onBeforeFocusChange?: (focused: Reference, index: number) => any,
+    dir?: 'auto' | 'ltr' | 'rtl',
 };
 
 export interface ILayout {
@@ -29,6 +30,7 @@ export const getLayoutBase = (onKeyDown: (event: KeyboardEvent, layout: ILayout)
             onFocusChanged: noop,
             onBeforeFocusChange: noop,
             focusOptions: { preventScroll: true },
+            dir: 'auto',
         };
 
         declare props: DeclareProps<Props, typeof Layout.defaultProps>;
@@ -61,7 +63,9 @@ export const getLayoutBase = (onKeyDown: (event: KeyboardEvent, layout: ILayout)
             ) {
                 return this.index;
             }
-            const targetIndex = focusableChildren.findIndex((ref) => ref.current === target);
+            const targetIndex = focusableChildren.findIndex(({ current }) => (
+                current === target || current?.hasDom?.(target)
+            ));
             return targetIndex !== -1 ? targetIndex : this.index;
         }
 

package/packages/focus/src/Layout/Horizontal.ts

@@ -1,11 +1,24 @@
-import { device } from '@24i/bigscreen-sdk/device';
-import { getLayoutBase, ILayout } from './Base';
+import { LEFT, RIGHT } from '@24i/bigscreen-sdk/device/keymap';
+import { isRtl } from '@24i/bigscreen-sdk/i18n';
+import { getLayoutBase, ILayout, Props } from './Base';
+
+const isHorizontalRtl = (dir: Props['dir']) => {
+    switch (dir) {
+        case 'rtl': return true;
+        case 'ltr': return false;
+        case 'auto':
+        default:
+            return isRtl();
+    }
+};
 
 const onKeyDown = (e: KeyboardEvent, layout: ILayout) => {
-    if (device.isDirectionLeft(e)) {
-        layout.backward(e);
-    } else if (device.isDirectionRight(e)) {
-        layout.forward(e);
+    if (!isHorizontalRtl(layout.props.dir)) {
+        if (LEFT.is(e)) layout.backward(e);
+        if (RIGHT.is(e)) layout.forward(e);
+    } else {
+        if (LEFT.is(e)) layout.forward(e);
+        if (RIGHT.is(e)) layout.backward(e);
     }
 };
 

package/packages/focus/src/Layout/__test__/Base.spec.ts

@@ -1,5 +1,6 @@
+import { IFocusable } from '../../IFocusable';
 import { getLayoutBase } from '../Base';
-import { rootRef, refChildA, refChildB, refChildC } from './shared';
+import { rootRef, refChildA, refChildB, refChildC, refChildD } from './shared';
 
 const mockKeydown = jest.fn();
 const mockEvent: any = {
@@ -159,4 +160,21 @@ describe('Focus Layout Base', () => {
         base.index = 2;
         expect(() => base.focusCurrentIndex()).toThrow();
     });
+
+    it('should take result of hasDom into account of determining current focus position', () => {
+        base = new Base({
+            domRef: rootRef,
+            children: 'children',
+            focusableChildren: [refChildA, refChildB, refChildC, refChildD],
+            onFocusChanged: jest.fn(),
+            onBeforeFocusChange: jest.fn(),
+        });
+        ((refChildD.current as IFocusable).hasDom as jest.MockedFn<
+        Exclude<IFocusable['hasDom'], undefined>
+        >).mockReturnValueOnce(true);
+        base.backward(mockEvent);
+        expect(base.index).toBe(2);
+        base.backward(mockEvent);
+        expect(base.index).toBe(1);
+    });
 });

package/packages/focus/src/Layout/__test__/Horizontal.spec.ts

@@ -1,6 +1,13 @@
+import { isRtl } from '@24i/bigscreen-sdk/i18n';
 import { Horizontal } from '../Horizontal';
 import { rootRef, refChildA, refChildB, refChildC } from './shared';
 
+jest.mock('@24i/bigscreen-sdk/i18n', () => ({
+    ...jest.requireActual('@24i/bigscreen-sdk/i18n'),
+    isRtl: jest.fn().mockReturnValue(false),
+}));
+const isRtlMock = isRtl as jest.MockedFn<typeof isRtl>;
+
 const mockEvent = {
     target: false,
     preventDefault: jest.fn(),
@@ -38,9 +45,50 @@ describe('Horizontal Focus Layout', () => {
         expect(horizontal.forward).toHaveBeenCalled();
     });
 
-    it('should call forward on LEFT', () => {
+    it('should call backward on LEFT', () => {
+        horizontal.setIndex(1);
+        horizontal.onKeyDown(mockLEFTEvent);
+        expect(horizontal.backward).toHaveBeenCalled();
+    });
+
+    it('should call backward on RIGHT when RTL', () => {
+        isRtlMock.mockReturnValueOnce(true);
+        horizontal.setIndex(1);
+        horizontal.onKeyDown(mockRIGHTEvent);
+        expect(horizontal.backward).toHaveBeenCalled();
+    });
+
+    it('should call forward on LEFT when RTL', () => {
+        isRtlMock.mockReturnValueOnce(true);
+        horizontal.onKeyDown(mockLEFTEvent);
+        expect(horizontal.forward).toHaveBeenCalled();
+    });
+
+    it('should call backward on RIGHT when forced RTL', () => {
+        horizontal.props.dir = 'rtl';
+        horizontal.setIndex(1);
+        horizontal.onKeyDown(mockRIGHTEvent);
+        expect(horizontal.backward).toHaveBeenCalled();
+    });
+
+    it('should call forward on LEFT when forced RTL', () => {
+        horizontal.props.dir = 'rtl';
+        horizontal.onKeyDown(mockLEFTEvent);
+        expect(horizontal.forward).toHaveBeenCalled();
+    });
+
+    it('should call backward on LEFT when RTL and forced LTR', () => {
+        isRtlMock.mockReturnValueOnce(true);
+        horizontal.props.dir = 'ltr';
         horizontal.setIndex(1);
         horizontal.onKeyDown(mockLEFTEvent);
         expect(horizontal.backward).toHaveBeenCalled();
     });
+
+    it('should call forward on RIGHT when RTL and forced LTR', () => {
+        isRtlMock.mockReturnValueOnce(true);
+        horizontal.props.dir = 'ltr';
+        horizontal.onKeyDown(mockRIGHTEvent);
+        expect(horizontal.forward).toHaveBeenCalled();
+    });
 });

package/packages/focus/src/Layout/__test__/shared.ts

@@ -1,4 +1,5 @@
 import { createRef } from '@24i/bigscreen-sdk/jsx';
+import { IFocusable } from '../../IFocusable';
 
 class ChildMock {
     focus = jest.fn();
@@ -10,6 +11,9 @@ export const rootRef = createRef(root);
 const childA = new ChildMock();
 const childB = new ChildMock();
 const childC = new ChildMock();
+const childD = new ChildMock();
+(childD as IFocusable).hasDom = jest.fn().mockReturnValue(false);
 export const refChildA = createRef(childA);
 export const refChildB = createRef(childB);
 export const refChildC = createRef(childC);
+export const refChildD = createRef(childD);