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

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

import { type PartialWithUndefined } from '@augment-vir/common';
import { ListenTarget } from 'typed-event-target';
import { type CurrentNavEntry, type NavEntry } from '../directives/nav-entry.js';
import { type NavTree } from '../nav-tree/nav-tree.js';
import { type AllNavControllerEvents } from './nav-controller-events.js';
import { NavAction, type NavigationInputs, type NavigationResult } from './navigate.js';
/**
 * Options for {@link NavController}.
 *
 * @category Internal
 */
export type NavControllerOptions = PartialWithUndefined<{
    /**
     * Always require an element within the nav tree to be focused.
     *
     * @default false
     */
    alwaysRequireFocused: boolean;
    /**
     * By default, element activation is triggered on mousedown. Set this to `true` to instead
     * activate it on `mouseup`.
     *
     * @default false
     */
    activateOnMouseUp: boolean;
}>;
/**
 * Allows navigation around the nav tree contained within the given `rootElement`. If there is no
 * nav tree, all operations simply do nothing. For a full example, see
 * {@link https://github.com/electrovir/device-navigation/blob/dev/src/test/elements/vir-test-app.element.ts | vir-test-app.element.ts}.
 *
 * @category Main
 * @example
 *
 * ```ts
 * import {NavController, NavDirection} from 'device-navigation';
 *
 * const navController = new NavController(host);
 *
 * window.addEventListener('keydown', (event) => {
 *     if (event.code === 'ArrowDown') {
 *         navController.navigate({direction: NavDirection.Down, allowWrapper: false});
 *     } else if (event.code === 'ArrowUp') {
 *         navController.navigate({direction: NavDirection.Up, allowWrapper: false});
 *     }
 *     // etc. all other navigation directions
 * });
 * ```
 */
export declare class NavController extends ListenTarget<AllNavControllerEvents> {
    readonly rootElement: HTMLElement;
    readonly options: NavControllerOptions;
    constructor(rootElement: HTMLElement, options?: NavControllerOptions);
    /** If `true`, the nav tree will rebuild on next operation. */
    needsUpdate: boolean;
    /** If true, all nav is prevented. */
    locked: boolean;
    protected navEntries: Set<Readonly<NavEntry>>;
    currentNavEntry: Readonly<CurrentNavEntry> | undefined;
    protected cachedNavTree: Readonly<NavTree> | undefined;
    /** Gets or builds the current nav tree. */
    protected getNavTree(): Readonly<NavTree>;
    /** Focus the default element for the whole tree. */
    focusDefaultElement(): void;
    /** Add a new {@link NavEntry} to this controller. */
    addNavEntry(navEntry: NavEntry): void;
    /** Remove a {@link NavEntry} from this controller. */
    removeNavEntry(navEntry: NavEntry): void;
    /** Sets the current nav entry with the given action. */
    triggerNavEntry(navEntry: Readonly<NavEntry> | undefined, enabled: boolean, navAction: NavAction.Activate): NavigationResult<NavAction.Activate>;
    /** Sets the current nav entry with the given action. */
    triggerNavEntry(navEntry: Readonly<NavEntry> | undefined, enabled: boolean, navAction: NavAction.Focus): NavigationResult<NavAction.Focus>;
    /** Navigate around the nav tree. */
    navigate({ direction, allowWrapping, }: Readonly<NavigationInputs>): NavigationResult<NavAction.Navigate>;
    /**
     * Enter into the currently focused node's children. Focuses the first child. Fails if there are
     * no children to focus.
     */
    enterInto(params: {
        fallbackToActivate: true;
    }): NavigationResult<NavAction.Enter | NavAction.Activate>;
    enterInto(params?: {
        fallbackToActivate?: false | undefined;
    } | undefined): NavigationResult<NavAction.Enter>;
    /** Activate the currently focused nav entry. */
    activate(): NavigationResult<NavAction.Activate>;
    /**
     * Shift focus from the currently focused node to its parent. If there is no parent, or rather
     * if the parent is the tree root, this fails.
     */
    exitOutOf(): NavigationResult<NavAction.Exit>;
    /** Navigate to siblings of the parent of the currently focused element, if they exist. */
    navigatePibling({ allowWrapping, direction, }: Readonly<NavigationInputs>): NavigationResult<NavAction.Pibling>;
    /** Builds the latest tree, sets it internally, and returns it. */
    buildNavTree(): NavTree;
}