@noriginmedia/norigin-spatial-navigation-core 3.0.0

package/README.md

@@ -0,0 +1,5 @@
+# Norigin Spatial Navigation Core
+
+Norigin Spatial Navigation Core is a framework-agnostic module providing the logic for spatial navigation in TV applications.
+
+For more detailed documentation and usage examples, visit our [Developer Portal](https://devportal.noriginmedia.com/docs/Norigin-Spatial-Navigation/)

package/dist/SpatialNavigation.d.ts

@@ -0,0 +1,281 @@
+import WritingDirection from './WritingDirection';
+export type Direction = 'up' | 'down' | 'left' | 'right';
+type DistanceCalculationMethod = 'center' | 'edges' | 'corners';
+type DistanceCalculationFunction = (refCorners: Corners, siblingCorners: Corners, isVerticalDirection: boolean, distanceCalculationMethod: DistanceCalculationMethod) => number;
+export declare const ROOT_FOCUS_KEY = "SN:ROOT";
+export interface FocusableComponentLayout {
+    left: number;
+    top: number;
+    readonly right: number;
+    readonly bottom: number;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    node: HTMLElement;
+}
+interface FocusableComponent {
+    focusKey: string;
+    node: HTMLElement;
+    parentFocusKey: string;
+    onEnterPress: (details?: KeyPressDetails) => void;
+    onEnterRelease: () => void;
+    onArrowPress: (direction: string, details: KeyPressDetails) => boolean;
+    onArrowRelease: (direction: string) => void;
+    onFocus: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+    onBlur: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+    onUpdateFocus: (focused: boolean) => void;
+    onUpdateHasFocusedChild: (hasFocusedChild: boolean) => void;
+    saveLastFocusedChild: boolean;
+    trackChildren: boolean;
+    preferredChildFocusKey?: string;
+    focusable: boolean;
+    isFocusBoundary: boolean;
+    focusBoundaryDirections?: Direction[];
+    autoRestoreFocus: boolean;
+    forceFocus: boolean;
+    lastFocusedChildKey?: string;
+    layout?: FocusableComponentLayout;
+    layoutUpdated?: boolean;
+}
+interface FocusableComponentUpdatePayload {
+    node: HTMLElement;
+    preferredChildFocusKey?: string;
+    focusable: boolean;
+    isFocusBoundary: boolean;
+    focusBoundaryDirections?: Direction[];
+    onEnterPress: (details?: KeyPressDetails) => void;
+    onEnterRelease: () => void;
+    onArrowPress: (direction: string, details: KeyPressDetails) => boolean;
+    onArrowRelease: (direction: string) => void;
+    onFocus: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+    onBlur: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+}
+interface FocusableComponentRemovePayload {
+    focusKey: string;
+}
+interface CornerCoordinates {
+    x: number;
+    y: number;
+}
+interface Corners {
+    a: CornerCoordinates;
+    b: CornerCoordinates;
+}
+export type PressedKeys = {
+    [index: string]: number;
+};
+/**
+ * Extra details about pressed keys passed on the key events
+ */
+export interface KeyPressDetails {
+    pressedKeys: PressedKeys;
+}
+/**
+ * Extra details passed from outside to be bounced back on other callbacks
+ */
+export interface FocusDetails {
+    event?: Event;
+    nativeEvent?: Event;
+    [key: string]: any;
+}
+export type BackwardsCompatibleKeyMap = {
+    [index: string]: string | number | (number | string)[];
+};
+export type KeyMap = {
+    [index: string]: (string | number)[];
+};
+declare class SpatialNavigationService {
+    private focusableComponents;
+    private visualDebugger;
+    /**
+     * Focus key of the currently focused element
+     */
+    private focusKey;
+    private shouldFocusDOMNode;
+    private shouldUseNativeEvents;
+    /**
+     * This collection contains focus keys of the elements that are having a child focused
+     * Might be handy for styling of certain parent components if their child is focused.
+     */
+    private parentsHavingFocusedChild;
+    /**
+     * When shouldFocusDOMNode is true, this prop specifies the focus options that should be passed to the element being focused.
+     */
+    private domNodeFocusOptions;
+    private enabled;
+    /**
+     * Used in the React Native environment
+     * In this mode, the library works as a "read-only" helper to sync focused
+     * states for the components when they are focused by the native focus engine
+     */
+    private nativeMode;
+    /**
+     * Throttling delay for key presses in milliseconds
+     */
+    private throttle;
+    /**
+     * Enables/disables throttling feature
+     */
+    private throttleKeypresses;
+    /**
+     * Storing pressed keys counter by the eventType
+     */
+    private pressedKeys;
+    /**
+     * Flag used to block key events from this service
+     */
+    private paused;
+    /**
+     * Enables/disables getBoundingClientRect
+     */
+    private useGetBoundingClientRect;
+    private keyDownEventListener;
+    private keyDownEventListenerThrottled;
+    private keyUpEventListener;
+    private keyMap;
+    private debug;
+    private logIndex;
+    private setFocusDebounced;
+    private writingDirection;
+    private distanceCalculationMethod;
+    private customDistanceCalculationFunction?;
+    /**
+     * Used to determine the coordinate that will be used to filter items that are over the "edge"
+     */
+    static getCutoffCoordinate(isVertical: boolean, isIncremental: boolean, isSibling: boolean, layout: FocusableComponentLayout, writingDirection: WritingDirection): number;
+    /**
+     * Returns two corners (a and b) coordinates that are used as a reference points
+     * Where "a" is always leftmost and topmost corner, and "b" is rightmost bottommost corner
+     */
+    static getRefCorners(direction: string, isSibling: boolean, layout: FocusableComponentLayout): {
+        a: {
+            x: number;
+            y: number;
+        };
+        b: {
+            x: number;
+            y: number;
+        };
+    };
+    /**
+     * Calculates if the sibling node is intersecting enough with the ref node by the secondary coordinate
+     */
+    static isAdjacentSlice(refCorners: Corners, siblingCorners: Corners, isVerticalDirection: boolean): boolean;
+    static getPrimaryAxisDistance(refCorners: Corners, siblingCorners: Corners, isVerticalDirection: boolean): number;
+    static getSecondaryAxisDistance(refCorners: Corners, siblingCorners: Corners, isVerticalDirection: boolean, distanceCalculationMethod: DistanceCalculationMethod, customDistanceCalculationFunction?: DistanceCalculationFunction): number;
+    /**
+     * Inspired by: https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS_for_TV/TV_remote_control_navigation#Algorithm_design
+     * Ref Corners are the 2 corners of the current component in the direction of navigation
+     * They are used as a base to measure adjacent slices
+     */
+    sortSiblingsByPriority(siblings: FocusableComponent[], currentLayout: FocusableComponentLayout, direction: string, focusKey: string): FocusableComponent[];
+    constructor();
+    init({ debug, visualDebug, nativeMode, throttle: throttleParam, throttleKeypresses, useGetBoundingClientRect, shouldFocusDOMNode, domNodeFocusOptions, shouldUseNativeEvents, rtl, distanceCalculationMethod, customDistanceCalculationFunction }?: {
+        debug?: boolean;
+        visualDebug?: boolean;
+        nativeMode?: boolean;
+        throttle?: number;
+        throttleKeypresses?: boolean;
+        useGetBoundingClientRect?: boolean;
+        shouldFocusDOMNode?: boolean;
+        domNodeFocusOptions?: {};
+        shouldUseNativeEvents?: boolean;
+        rtl?: boolean;
+        distanceCalculationMethod?: DistanceCalculationMethod;
+        customDistanceCalculationFunction?: DistanceCalculationFunction;
+    }): void;
+    setThrottle({ throttle: throttleParam, throttleKeypresses }?: {
+        throttle?: number;
+        throttleKeypresses?: boolean;
+    }): void;
+    destroy(): void;
+    getEventType(keyCode: number | string): string;
+    static getKeyCode(event: KeyboardEvent): string | number;
+    bindEventHandlers(): void;
+    unbindEventHandlers(): void;
+    onEnterPress(keysDetails: KeyPressDetails): void;
+    onEnterRelease(): void;
+    onArrowPress(direction: string, keysDetails: KeyPressDetails): boolean;
+    onArrowRelease(direction: string): void;
+    /**
+     * Move focus by direction, if you can't use buttons or focusing by key.
+     *
+     * @example
+     * navigateByDirection('right') // The focus is moved to right
+     */
+    navigateByDirection(direction: string, focusDetails: FocusDetails): void;
+    /**
+     * This function navigates between siblings OR goes up by the Tree
+     * Based on the Direction
+     */
+    smartNavigate(direction: string, fromParentFocusKey: string, focusDetails: FocusDetails): void;
+    saveLastFocusedChildKey(component: FocusableComponent, focusKey: string): void;
+    log(functionName: string, debugString: string, ...rest: any[]): void;
+    /**
+     * Returns the current focus key
+     */
+    getCurrentFocusKey(): string;
+    /**
+     * Returns the focus key to which focus can be forced if there are force-focusable components.
+     * A component closest to the top left viewport corner (0,0) is returned.
+     */
+    getForcedFocusKey(): string | undefined;
+    /**
+     * This function tries to determine the next component to Focus
+     * It's either the target node OR the one down by the Tree if node has children components
+     * Based on "targetFocusKey" which means the "intended component to focus"
+     */
+    getNextFocusKey(targetFocusKey: string): string;
+    addFocusable({ focusKey, node, parentFocusKey, onEnterPress, onEnterRelease, onArrowPress, onArrowRelease, onFocus, onBlur, saveLastFocusedChild, trackChildren, onUpdateFocus, onUpdateHasFocusedChild, preferredChildFocusKey, autoRestoreFocus, forceFocus, focusable, isFocusBoundary, focusBoundaryDirections }: FocusableComponent): void;
+    removeFocusable({ focusKey }: FocusableComponentRemovePayload): void;
+    getNodeLayoutByFocusKey(focusKey: string): FocusableComponentLayout;
+    setCurrentFocusedKey(newFocusKey: string, focusDetails: FocusDetails): void;
+    updateParentsHasFocusedChild(focusKey: string, focusDetails: FocusDetails): void;
+    updateParentsLastFocusedChild(focusKey: string): void;
+    getKeyMap(): KeyMap;
+    setKeyMap(keyMap: BackwardsCompatibleKeyMap): void;
+    isFocusableComponent(focusKey: string): boolean;
+    /**
+     * Checks whether the focusableComponent is actually participating in spatial navigation (in other words, is a
+     * 'focusable' focusableComponent). Seems less confusing than calling it isFocusableFocusableComponent()
+     */
+    isParticipatingFocusableComponent(focusKey: string): boolean;
+    onIntermediateNodeBecameFocused(focusKey: string, focusDetails: FocusDetails): void;
+    onIntermediateNodeBecameBlurred(focusKey: string, focusDetails: FocusDetails): void;
+    pause(): void;
+    resume(): void;
+    setFocus(focusKey: string, focusDetails?: FocusDetails): void;
+    updateAllLayouts(): void;
+    updateLayout(focusKey: string): void;
+    updateFocusable(focusKey: string, { node, preferredChildFocusKey, focusable, isFocusBoundary, focusBoundaryDirections, onEnterPress, onEnterRelease, onArrowPress, onFocus, onBlur }: FocusableComponentUpdatePayload): void;
+    isNativeMode(): boolean;
+    doesFocusableExist(focusKey: string): boolean;
+    /**
+     * This function updates the writing direction
+     * @param rtl whether the writing direction is right-to-left
+     */
+    updateRtl(rtl: boolean): void;
+}
+/**
+ * Export singleton
+ */
+export declare const SpatialNavigation: SpatialNavigationService;
+export declare const init: ({ debug, visualDebug, nativeMode, throttle: throttleParam, throttleKeypresses, useGetBoundingClientRect, shouldFocusDOMNode, domNodeFocusOptions, shouldUseNativeEvents, rtl, distanceCalculationMethod, customDistanceCalculationFunction }?: {
+    debug?: boolean;
+    visualDebug?: boolean;
+    nativeMode?: boolean;
+    throttle?: number;
+    throttleKeypresses?: boolean;
+    useGetBoundingClientRect?: boolean;
+    shouldFocusDOMNode?: boolean;
+    domNodeFocusOptions?: {};
+    shouldUseNativeEvents?: boolean;
+    rtl?: boolean;
+    distanceCalculationMethod?: DistanceCalculationMethod;
+    customDistanceCalculationFunction?: DistanceCalculationFunction;
+}) => void, setThrottle: ({ throttle: throttleParam, throttleKeypresses }?: {
+    throttle?: number;
+    throttleKeypresses?: boolean;
+}) => void, destroy: () => void, setKeyMap: (keyMap: BackwardsCompatibleKeyMap) => void, setFocus: (focusKey: string, focusDetails?: FocusDetails) => void, navigateByDirection: (direction: string, focusDetails: FocusDetails) => void, pause: () => void, resume: () => void, updateAllLayouts: () => void, getCurrentFocusKey: () => string, doesFocusableExist: (focusKey: string) => boolean, updateRtl: (rtl: boolean) => void;
+export {};

package/dist/VisualDebugger.d.ts

@@ -0,0 +1,21 @@
+import WritingDirection from './WritingDirection';
+interface NodeLayout {
+    left: number;
+    top: number;
+    readonly right: number;
+    readonly bottom: number;
+    width: number;
+    height: number;
+}
+declare class VisualDebugger {
+    private debugCtx;
+    private layoutsCtx;
+    private writingDirection;
+    constructor(writingDirection: WritingDirection);
+    static createCanvas(id: string, zIndex: string, writingDirection: WritingDirection): CanvasRenderingContext2D;
+    clear(): void;
+    clearLayouts(): void;
+    drawLayout(layout: NodeLayout, focusKey: string, parentFocusKey: string): void;
+    drawPoint(x: number, y: number, color?: string, size?: number): void;
+}
+export default VisualDebugger;

package/dist/WritingDirection.d.ts

@@ -0,0 +1,5 @@
+declare enum WritingDirection {
+    LTR = 0,
+    RTL = 1
+}
+export default WritingDirection;

package/dist/__tests__/SpatialNavigation.RTL.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/SpatialNavigation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/domNodes.d.ts

@@ -0,0 +1,3 @@
+export declare const createRootNode: () => void;
+export declare const createHorizontalLayout: () => void;
+export declare const createVerticalLayout: () => void;

package/dist/__tests__/measureLayout.test.d.ts

@@ -0,0 +1 @@
+export {};