@noriginmedia/norigin-spatial-navigation-core 3.0.0 → 3.1.0-beta.0

package/dist/Scheduler.d.ts

@@ -0,0 +1,16 @@
+type Task = () => unknown | Promise<unknown>;
+/**
+ * Scheduler provides a simple way to queue and execute tasks in a strict sequence.
+ * - Regular tasks are run one after another; if a new task is scheduled before the current one starts, it replaces the pending next task.
+ * - Priority tasks are added to a separate queue and will be executed before any remaining regular tasks.
+ */
+export default class Scheduler {
+    private currentTask;
+    private nextTask;
+    private nextPriorityTasks;
+    private tick;
+    bind<A extends unknown[], R>(fn: (...args: A) => R | Promise<R>, context: any): (...args: A) => Promise<void>;
+    schedule(task: Task): void;
+    schedulePriority(task: Task): void;
+}
+export {};

package/dist/SpatialNavigation.d.ts

@@ -1,4 +1,10 @@
+import { type LayoutAdapter } from './adapter/types';
 import WritingDirection from './WritingDirection';
+export interface NodeTypeOverrides {
+}
+export type NodeType = NodeTypeOverrides extends {
+    node: infer N;
+} ? N : HTMLElement;
 export type Direction = 'up' | 'down' | 'left' | 'right';
 type DistanceCalculationMethod = 'center' | 'edges' | 'corners';
 type DistanceCalculationFunction = (refCorners: Corners, siblingCorners: Corners, isVerticalDirection: boolean, distanceCalculationMethod: DistanceCalculationMethod) => number;
@@ -6,17 +12,17 @@ export declare const ROOT_FOCUS_KEY = "SN:ROOT";
 export interface FocusableComponentLayout {
     left: number;
     top: number;
-    readonly right: number;
-    readonly bottom: number;
+    right: number;
+    bottom: number;
     width: number;
     height: number;
     x: number;
     y: number;
-    node: HTMLElement;
+    node: NodeType;
 }
-interface FocusableComponent {
+export interface FocusableComponent {
     focusKey: string;
-    node: HTMLElement;
+    node: NodeType;
     parentFocusKey: string;
     onEnterPress: (details?: KeyPressDetails) => void;
     onEnterRelease: () => void;
@@ -36,10 +42,10 @@ interface FocusableComponent {
     forceFocus: boolean;
     lastFocusedChildKey?: string;
     layout?: FocusableComponentLayout;
-    layoutUpdated?: boolean;
+    layoutUpdatedAt?: number;
 }
 interface FocusableComponentUpdatePayload {
-    node: HTMLElement;
+    node: NodeType;
     preferredChildFocusKey?: string;
     focusable: boolean;
     isFocusBoundary: boolean;
@@ -85,7 +91,28 @@ export type BackwardsCompatibleKeyMap = {
 export type KeyMap = {
     [index: string]: (string | number)[];
 };
-declare class SpatialNavigationService {
+export type SpatialNavigationServiceOptions = {
+    debug: boolean;
+    visualDebug: boolean;
+    throttle: number;
+    throttleKeypresses: boolean;
+    /**
+     * @deprecated Use layoutAdapter API instead.
+     */
+    useGetBoundingClientRect: boolean;
+    shouldFocusDOMNode: boolean;
+    domNodeFocusOptions: FocusOptions;
+    shouldUseNativeEvents: boolean;
+    rtl: boolean;
+    /**
+     * Can be a class (constructor) that implements LayoutAdapter,
+     * or an object that partially implements LayoutAdapter.
+     */
+    layoutAdapter?: (new (...args: any[]) => LayoutAdapter) | Partial<LayoutAdapter>;
+    distanceCalculationMethod: DistanceCalculationMethod;
+    customDistanceCalculationFunction?: DistanceCalculationFunction;
+};
+export declare class SpatialNavigationService {
     private focusableComponents;
     private visualDebugger;
     /**
@@ -104,12 +131,6 @@ declare class SpatialNavigationService {
      */
     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
      */
@@ -126,10 +147,7 @@ declare class SpatialNavigationService {
      * Flag used to block key events from this service
      */
     private paused;
-    /**
-     * Enables/disables getBoundingClientRect
-     */
-    private useGetBoundingClientRect;
+    private layoutAdapter;
     private keyDownEventListener;
     private keyDownEventListenerThrottled;
     private keyUpEventListener;
@@ -140,6 +158,12 @@ declare class SpatialNavigationService {
     private writingDirection;
     private distanceCalculationMethod;
     private customDistanceCalculationFunction?;
+    private scheduler;
+    get options(): {
+        shouldFocusDOMNode: boolean;
+        domNodeFocusOptions: FocusOptions;
+        shouldUseNativeEvents: boolean;
+    };
     /**
      * Used to determine the coordinate that will be used to filter items that are over the "edge"
      */
@@ -171,27 +195,13 @@ declare class SpatialNavigationService {
      */
     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;
+    init({ debug, visualDebug, throttle: throttleParam, throttleKeypresses, useGetBoundingClientRect, layoutAdapter, shouldFocusDOMNode, domNodeFocusOptions, shouldUseNativeEvents, rtl, distanceCalculationMethod, customDistanceCalculationFunction }?: Partial<SpatialNavigationServiceOptions>): 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;
@@ -204,12 +214,12 @@ declare class SpatialNavigationService {
      * @example
      * navigateByDirection('right') // The focus is moved to right
      */
-    navigateByDirection(direction: string, focusDetails: FocusDetails): void;
+    navigateByDirection(direction: string, focusDetails: FocusDetails): Promise<void>;
     /**
      * This function navigates between siblings OR goes up by the Tree
      * Based on the Direction
      */
-    smartNavigate(direction: string, fromParentFocusKey: string, focusDetails: FocusDetails): void;
+    smartNavigate(direction: string, fromParentFocusKey: string, focusDetails: FocusDetails): Promise<void>;
     saveLastFocusedChildKey(component: FocusableComponent, focusKey: string): void;
     log(functionName: string, debugString: string, ...rest: any[]): void;
     /**
@@ -226,10 +236,10 @@ declare class SpatialNavigationService {
      * 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;
+    getNextFocusKey(targetFocusKey: string): Promise<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;
+    getNodeLayoutByFocusKey(focusKey: string): Promise<FocusableComponentLayout>;
     setCurrentFocusedKey(newFocusKey: string, focusDetails: FocusDetails): void;
     updateParentsHasFocusedChild(focusKey: string, focusDetails: FocusDetails): void;
     updateParentsLastFocusedChild(focusKey: string): void;
@@ -245,11 +255,10 @@ declare class SpatialNavigationService {
     onIntermediateNodeBecameBlurred(focusKey: string, focusDetails: FocusDetails): void;
     pause(): void;
     resume(): void;
-    setFocus(focusKey: string, focusDetails?: FocusDetails): void;
-    updateAllLayouts(): void;
-    updateLayout(focusKey: string): void;
+    setFocus(focusKey: string, focusDetails?: FocusDetails): Promise<void>;
+    updateAllLayouts(): Promise<void>;
+    updateLayout(focusKey: string): Promise<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
@@ -261,21 +270,8 @@ declare class SpatialNavigationService {
  * 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 }?: {
+export declare const init: ({ debug, visualDebug, throttle: throttleParam, throttleKeypresses, useGetBoundingClientRect, layoutAdapter, shouldFocusDOMNode, domNodeFocusOptions, shouldUseNativeEvents, rtl, distanceCalculationMethod, customDistanceCalculationFunction }?: Partial<SpatialNavigationServiceOptions>) => 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;
+}) => void, destroy: () => void, setKeyMap: (keyMap: BackwardsCompatibleKeyMap) => void, setFocus: (focusKey: string, focusDetails?: FocusDetails) => Promise<void>, navigateByDirection: (direction: string, focusDetails: FocusDetails) => Promise<void>, pause: () => void, resume: () => void, updateAllLayouts: () => Promise<void>, getCurrentFocusKey: () => string, doesFocusableExist: (focusKey: string) => boolean, updateRtl: (rtl: boolean) => void;
 export {};

package/dist/adapter/getboundingclientrect.d.ts

@@ -0,0 +1,15 @@
+import { type FocusableComponent } from '../SpatialNavigation';
+import BaseWebAdapter from './web';
+export default class GetBoundingClientRectAdapter extends BaseWebAdapter {
+    measureLayout: (component: FocusableComponent) => Promise<{
+        node: HTMLElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        left: number;
+        top: number;
+        right: any;
+        bottom: any;
+    }>;
+}

package/dist/adapter/types.d.ts

@@ -0,0 +1,15 @@
+import { type FocusableComponent, type FocusableComponentLayout } from '../SpatialNavigation';
+export type Key = 'left' | 'right' | 'up' | 'down' | 'enter';
+export type KeyDownEventListener = (key: Key, event: Event) => void;
+export type KeyUpEventListener = (key: Key) => void;
+export type AddEventListenersOptions = {
+    keyDown?: KeyDownEventListener;
+    keyUp?: KeyUpEventListener;
+};
+export interface LayoutAdapter {
+    addEventListeners: (options: AddEventListenersOptions) => void;
+    removeEventListeners: () => void;
+    measureLayout: (component: FocusableComponent) => Promise<FocusableComponentLayout>;
+    blurNode: (component: FocusableComponent) => void;
+    focusNode: (component: FocusableComponent) => void;
+}

package/dist/adapter/web.d.ts

@@ -0,0 +1,23 @@
+import { type FocusableComponent, type SpatialNavigationService } from '../SpatialNavigation';
+import { type AddEventListenersOptions, type LayoutAdapter } from './types';
+export default class BaseWebAdapter implements LayoutAdapter {
+    private service;
+    constructor(service: SpatialNavigationService);
+    private keyDownEventListener;
+    private keyUpEventListener;
+    addEventListeners({ keyDown, keyUp }: AddEventListenersOptions): void;
+    removeEventListeners(): void;
+    measureLayout: (component: FocusableComponent) => Promise<{
+        node: HTMLElement;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        left: number;
+        top: number;
+        right: any;
+        bottom: any;
+    }>;
+    blurNode: (component: FocusableComponent) => void;
+    focusNode: (component: FocusableComponent) => void;
+}