@noriginmedia/norigin-spatial-navigation - npm Package Compare versions

Comparing version 2.2.1 to 2.2.2

dist/SpatialNavigation.d.ts

@@ -0,1 +1,2 @@
+import WritingDirection from './WritingDirection';
 export declare type Direction = 'up' | 'down' | 'left' | 'right';
@@ -16,2 +17,40 @@ declare type DistanceCalculationMethod = 'center' | 'edges' | 'corners';
 }
+interface FocusableComponent {
+    focusKey: string;
+    node: HTMLElement;
+    parentFocusKey: string;
+    onEnterPress: (details?: KeyPressDetails) => void;
+    onEnterRelease: () => void;
+    onArrowPress: (direction: string, details: KeyPressDetails) => boolean;
+    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;
+    onFocus: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+    onBlur: (layout: FocusableComponentLayout, details: FocusDetails) => void;
+}
+interface FocusableComponentRemovePayload {
+    focusKey: string;
+}
 interface CornerCoordinates {
@@ -48,2 +87,177 @@ x: 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;
+    /**
+     * 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, 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 }?: {
@@ -50,0 +264,0 @@ debug?: boolean;

dist/VisualDebugger.d.ts

@@ -1,2 +0,2 @@
-import WritingDirection from "./WritingDirection";
+import WritingDirection from './WritingDirection';
 interface NodeLayout {
@@ -3,0 +3,0 @@ left: number;

package.json

 {
   "name": "@noriginmedia/norigin-spatial-navigation",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "React hooks based Spatial Navigation solution",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

README.md

@@ -275,2 +275,5 @@ # Norigin Spatial Navigation
 ## Top Level exports
+### `SpatialNavigation` (advanced)
+Top level API class singleton that provides access to the Navigation Service and its methods. Not recommended for beginners as it provides access to all internal methods of the core navigation service.
+
 ### `init`
@@ -277,0 +280,0 @@ #### Init options

New alerts

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

80817

increased by13.93%

Lines of code

376

increased by133.54%

Number of lines in readme file

700

increased by0.43%

Number of medium supply chain risk alerts

1

decreased by-50%

No dependency changes