device-navigation/dist/nav-controller/navigate.d.ts

Navigate HTML elements in two dimensions with non-pointer devices.

import { type Coords } from '@augment-vir/common';
import { type CurrentNavEntry } from '../directives/nav-entry.js';
import { type NavTree, type NavTreeNode } from '../nav-tree/nav-tree.js';
/**
 * Inputs for controlling navigation.
 *
 * @category Internal
 */
export type NavigationInputs = {
    /**
     * The direction to navigate within the tree. Note that 1 dimensional navigation treads up and
     * left as the same, down and right as the same.
     */
    direction: NavDirection;
    /** Set to true to allow navigation to wrap. */
    allowWrapping: boolean;
};
/**
 * All the possible nav directions.
 *
 * @category Internal
 */
export declare enum NavDirection {
    Up = "up",
    Down = "down",
    Left = "left",
    Right = "right"
}
/**
 * All possible nav actions.
 *
 * @category Internal
 */
export declare enum NavAction {
    Enter = "enter",
    Exit = "exit",
    Activate = "activate",
    Focus = "focus",
    Navigate = "navigate",
    Pibling = "pibling"
}
/**
 * Maps NavAction to the relevant {@link NavDirection} type for the `direction` property in
 * {@link NavigationResult}.
 *
 * @category Internal
 */
export type NavActionToDirectionType = {
    [NavAction.Enter]: undefined;
    [NavAction.Exit]: undefined;
    [NavAction.Activate]: undefined;
    [NavAction.Focus]: undefined;
    [NavAction.Navigate]: NavDirection;
    [NavAction.Pibling]: NavDirection;
};
/**
 * Data which describes the result of an attempted navigation action.
 *
 * @category Internal
 */
export type NavigationResult<Action extends NavAction = NavAction> = ({
    /** Indicates that the intended navigation succeeded or failed. */
    success: true;
    /** When true, indicates that the performed navigation resulted in a wrap. */
    wrapped: boolean;
    /**
     * When true, indicates that there was no valid starting point to start the navigation
     * from, so a default behavior was taken. Most navigation actions do not support this
     * behavior.
     */
    defaulted: boolean;
    /** The element that the performed navigation focused. */
    newElement: HTMLElement;
    coords: Coords;
} | {
    /** Indicates that the intended navigation succeeded or failed. */
    success: false;
    /** The reason why the intended navigation did not succeed. */
    reason: string;
}) & {
    navAction: Action;
    direction: NavActionToDirectionType[Action];
};
/**
 * Finds the default node to select within the given node.
 *
 * @category Internal
 */
export declare function findDefaultChild(children: ReadonlyArray<ReadonlyArray<NavTreeNode>>): {
    node: NavTreeNode;
    coords: Coords;
} | undefined;
/**
 * Navigate around the nav tree.
 *
 * @category Internal
 */
export declare function navigate(navTree: NavTree, currentlyFocused: CurrentNavEntry | undefined, 
/**
 * The direction to navigate within the tree. Note that 1 dimensional navigation treads up and
 * left as the same, down and right as the same.
 */
direction: NavDirection, 
/** Set to true to allow navigation to wrap. */
allowWrapping: boolean): NavigationResult<NavAction.Navigate>;
/**
 * Navigate only to piblings (siblings of parent).
 *
 * @category Internal
 */
export declare function navigatePibling(currentlyFocused: Readonly<CurrentNavEntry>, direction: NavDirection, allowWrapping: boolean): NavigationResult<NavAction.Pibling>;