@empathyco/x-components/types/services/directional-focus-navigation.service.d.ts

Empathy X Components

import type { ArrowKey } from '../utils/types';
import type { SpatialNavigation } from './services.types';
/**
 * Implementation of {@link SpatialNavigation} using directional focus.
 *
 * @public
 */
export declare class DirectionalFocusNavigationService implements SpatialNavigation {
    /**
     * The {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement | HTMLElement} that
     * contains the navigable elements.
     */
    private readonly container;
    /**
     * Comma separated focusable selectors to look up.
     */
    private readonly focusableSelectors;
    /**
     * The HTMLElement that is currently on focus and used as reference to navigateTo from.
     */
    private origin;
    /**
     * The DOMRect of the origin Element.
     */
    private originRect;
    /**
     * Direction of the navigation.
     */
    private direction;
    /**
     * Weight of the projected intersection area weight in the
     * {@link DirectionalFocusNavigationService.getDistanceScore | getDistanceScore} formula.
     */
    private readonly intersectionAreaWeight;
    /**
     * Weight of the absolute distance on the orthogonal axis between to elements when navigating
     * left or right. Used to calculate the displacement in
     * {@link DirectionalFocusNavigationService.getDisplacementAndAlignment |
     * getDisplacementAndAlignment}.
     */
    private readonly orthogonalWeightHorizontal;
    /**
     * Weight of the absolute distance on the orthogonal axis between to elements when navigating
     * up or down. Used to calculate the displacement in
     * {@link DirectionalFocusNavigationService.getDisplacementAndAlignment |
     * getDisplacementAndAlignment}.
     */
    private readonly orthogonalWeightVertical;
    /**
     * Weight of the degree of alignment between two elements when calculating the alignment in
     * {@link DirectionalFocusNavigationService.getDisplacementAndAlignment |
     * getDisplacementAndAlignment}.
     */
    private readonly alignWeight;
    /**
     * Set of functions to filter out candidates based on the navigation's direction.
     */
    private readonly filterFunction;
    /**
     * Constructor for the {@link DirectionalFocusNavigationService}.
     *
     * @param container - The element that contains the navigable elements.
     * @param focusableSelectors - A comma separated string with the focusable selectors to look up.
     */
    constructor(
    /**
     * The {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement | HTMLElement} that
     * contains the navigable elements.
     */
    container: HTMLElement, 
    /**
     * Comma separated focusable selectors to look up.
     */
    focusableSelectors?: string);
    /**
     * Get the element that would be the next one to be navigated to based on the direction of the
     * arrow key pressed. If there are no possible candidates the element to focus would be the one on
     * currently on focus or the first one in the container.
     *
     * @param arrowKey - The arrow key that was pressed.
     *
     * @returns The element to navigate to.
     */
    navigateTo(arrowKey: ArrowKey): HTMLElement;
    /**
     * Gets focusable elements within the container.
     *
     * @returns List of focusable elements.
     * @internal
     */
    private getFocusableElements;
    /**
     * Updates the origin with the current document active element.
     *
     * @remarks
     * This also covers cases when the user might have iterated through the DOM using the TAB or
     * SHIFT+TAB keys.
     */
    private updateOrigin;
    /**
     * Finds the closest candidate to the origin from a list of candidates.
     *
     * @remarks
     * If there are no candidates the origin will be retrieved as best candidate.
     *
     * @param rawCandidates - List of all candidates.
     *
     * @returns The closest candidate to the origin or origin if there's none.
     * @internal
     */
    private getBestCandidate;
    /**
     * Filters out candidates that can't be candidates based on the direction of the navigation and
     * if they are visible and enabled.
     *
     * @param rawCandidates - List of all candidates.
     *
     * @returns List of filtered candidates.
     * @internal
     */
    filterCandidates(rawCandidates: HTMLElement[]): HTMLElement[];
    /**
     * Checks if the provided candidate is not the origin, is visible, enabled  and in the correct
     * direction to be a valid candidate.
     *
     * @param candidate - The candidate element.
     * @returns If the candidate is valid for the navigation.
     * @internal
     */
    private isValidCandidate;
    /**
     * Checks if the provided candidate is visible.
     *
     * @param candidate - The candidate element.
     * @returns If the candidate is visible.
     * @internal
     */
    private isCandidateVisible;
    /**
     * Checks if the provided candidate is disabled and if the tabindex allows the element to be
     * focused.
     *
     * @param candidate - The candidate element.
     * @returns If candidate's attributes allow it to be focused.
     * @internal
     */
    private hasFocusCompatibleAttributes;
    /**
     * Checks if the provided candidate is in the direction the navigation is going.
     *
     * @param candidate - The candidate element.
     * @returns If the candidate is in the correct direction.
     * @internal
     */
    private isInNavigateDirection;
    /**
     * Calculates the candidate's score for it to be the next element to navigateTo to based on a
     * formula that takes into account euclidean distance, displacement, alignment and
     * intersection area relative to the origin element.
     *
     * @param candidate - The candidate element.
     *
     * @returns The candidate score for best candidate.
     * @internal
     */
    private getDistanceScore;
    /**
     * Gets the closest point to origin within the candidate and to the candidate within the origin
     * based on the navigation direction.
     *
     * @param candidateRect - The DOMRect of the candidate.
     *
     * @returns The candidate's closest Points to the origin.
     * @internal
     */
    private getComparisionPoints;
    /**
     * Set parallel values between candidate and origin based on the navigation direction and
     * returns them.
     *
     * @param points - Current values for the candidate and origin's points.
     * @param candidateRect - The DOMRect of the candidate.
     * @returns Candidate and origin points with parallel values set.
     * @internal
     */
    private setParallelPointValues;
    /**
     * Set orthogonal values between candidate and origin based on the navigation direction and
     * returns them.
     *
     * @param points - Current values for the candidate and origin's points.
     * @param candidateRect - The DOMRect of the candidate.
     * @returns Candidate and origin points with orthogonal values set.
     * @internal
     */
    private setOrthogonalPointValues;
    /**
     * Calculates the displacement and alignment values for the candidate relative to the origin.
     *
     * @param candidateRect - The DOMRect of the candidate.
     * @param intersection - Projected intersection between candidate and origin.
     * @param absoluteDistances - Absolute distances between candidate and origin points.
     *
     * @returns Displacement and alignment values.
     * @internal
     */
    private getDisplacementAndAlignment;
    /**
     * Calculates the projected intersection between two
     * {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMRect | rects}.
     *
     * @param rect1 - First {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMRect | rect}.
     * @param rect2 - Second {@link https://developer.mozilla.org/en-US/docs/Web/API/DOMRect | rect}.
     *
     * @returns The intersection.
     * @internal
     */
    private getIntersection;
    /**
     * Checks that both DOMRect are aligned based on the provided direction.
     *
     * @param rect1 - The first DOMRect.
     * @param rect2 - The DOMRect that the first one will be compared to.
     *
     * @returns If the DOMRect are aligned.
     * @internal
     */
    private areAligned;
    /**
     * Checks that the first DOMRect is below the second one.
     *
     * @param rect1 - The first DOMRect.
     * @param rect2 - The DOMRect that the first one will be compared to.
     *
     * @returns If it's below.
     * @internal
     */
    private isBelow;
    /**
     * Checks that the first DOMRect is to the right side of the second one.
     *
     * @param rect1 - The first DOMRect.
     * @param rect2 - The DOMRect that the first one will be compared to.
     *
     * @returns If it's to the right side.
     * @internal
     */
    private isRightSide;
}
//# sourceMappingURL=directional-focus-navigation.service.d.ts.map