@momentum-ui/react-collaboration
Version:
Cisco Momentum UI Framework for React Collaboration Applications
105 lines (104 loc) • 4.55 kB
TypeScript
import React from 'react';
import { Direction, ExpandedBoundingRect, FarEdge, Rect, RectWithMidPoint, RelativeElementDistance, SpatialNavigationContextValue } from './SpatialNavigationProvider.types';
export declare const SpatialNavigationContext: React.Context<import("./SpatialNavigationProvider.types").NavKeyMapping & {
directionKeys: string[];
}>;
/**
* Get the current spatial navigation context.
*/
export declare const useSpatialNavigationContext: () => SpatialNavigationContextValue;
/**
* Calculate the center point of the element
*/
export declare const getElementRectWithMidPoint: (element: HTMLElement) => RectWithMidPoint;
/**
* Complex components can have nested focusable items, for example
* List or Tree nodes
*
* Spatial navigation can process 4 cases:
* - none - no nested focusable item (default)
* - horizontal - the focusable items are in a row
* - vertical - the focusable items are in a column
* - both - the focusable items are in a grid
*
* @param el - checked element
*/
export declare const getNestedFocusableDirection: (el: HTMLElement) => FarEdge;
/**
* Calculate distance between the closest edges of the passed bounding boxes for the specified direction
*
* @param a bounding box 1
* @param b bounding box 2
* @param dir direction specify which edge measured
* @param farEdge
* @returns distance
*/
export declare const getEdgeDistance: (a: Rect, b: Rect, dir: Direction, farEdge?: FarEdge) => number;
/**
* Calculate expanded bounding boxes in all four directions with the specified size
*
* @param baseRect
* @param size
*/
export declare const getExpandedRect: (baseRect: Rect, size: number) => ExpandedBoundingRect;
/**
* Rectangle overlap check
*
* @param a first rectangle
* @param b second rectangle
* @return `true` when the two rectangles overlap otherwise `false`
*/
export declare const isRectOverlap: (a: Rect, b: Rect) => boolean;
/**
* Get the relative position of the element from the active element.
*
* @remarks
* - `edgeDistance` is a distance between the closest edge of the `element` and one of active element's edge
* the actual edge depends on the `farEdge` parameter
* - `distance` is `infinite` when `element` is not in the specified `direction`
* - `edgeDistance` is `infinite` when the `element` does not overlap the active element's expanded bounding rect
* on the specified `direction`
* - in the return value both `edgeDistance` and `distance` are the square of the real distance
*
* @param element
* @param direction
* @param activeElementMidPoint
* @param activeElementExpandedRects
* @param farEdge
*/
export declare const getElementRelativeDistances: (element: HTMLElement, direction: Direction, activeElementMidPoint: RectWithMidPoint, activeElementExpandedRects: ExpandedBoundingRect, farEdge: FarEdge) => RelativeElementDistance;
/**
* Calculate the distance of the focusable elements form the active element
* and return the sorted list of elements based on the distance.
* The first element is the closest.
*
* @param activeEl Active/focused Dom element
* @param focusableElements All focusable elements
* @param direction Direction of the navigation
*/
export declare const orderElementsByDistance: (activeEl: HTMLElement, focusableElements: HTMLElement[], direction: Direction) => RelativeElementDistance[];
/**
* This hook helps to integrate spatial navigation with the radio group.
*
* Stop event propagation when user navigate between radio buttons with arrow keys except
* when the first or last radio button is focused and the user presses "prev" (left or up) or "next" (right or down) arrow keys.
*
* @param onKeyDown Optional onKeyDown event handler
*/
export declare const useSpatialRadioGroupNavigation: (onKeyDown?: (e: React.KeyboardEvent<HTMLElement>) => void) => (evt: React.KeyboardEvent<HTMLElement>) => void;
/**
* This function helps to visually debug spatial navigation
*
* Press Shift + Arrow keys to inspect navigation in the given direction.
* Pressing any other key hide the debug layer
*
* Legends:
* - red rectangle - focused element
* - green rectangle - expanded bounding box of the focused element for edge distance calculation
* - blue rectangle - considered as next focusable elements
* - white/gray dot - mid-point of the element for distance calculation, it fades based on the distance
* - # - order number #1 will be the next focused element
* - ed - edge distance
* - d - distance
*/
export declare const visualDebugger: (root?: HTMLElement) => void;