device-navigation/dist/directives/nav-entry.d.ts

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

import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
import { type NavController } from '../nav-controller/nav-controller.js';
import { NavAction } from '../nav-controller/navigate.js';
import { type NavTreeNode } from '../nav-tree/nav-tree.js';
import { type WalkResult } from '../nav-tree/walk-nav-tree.js';
/**
 * The currently focused or activated nav entry.
 *
 * @category Internal
 */
export type CurrentNavEntry = {
    entry: Readonly<NavEntry>;
    navAction: NavAction.Activate | NavAction.Focus;
    position: Readonly<WalkResult>;
};
/**
 * Values for the nav attribute that `nav` applies to elements.
 *
 * @category Internal
 */
export declare enum NavValue {
    Disabled = "disabled",
    Group = "group",
    Focused = "focused",
    Active = "active"
}
/**
 * The attribute which the `nav` directive applies to elements with a value of {@link NavValue}.
 *
 * @category Internal
 */
export declare const navAttribute: {
    /** Name of the attribute. */
    name: string;
    /**
     * Use this to generate a query selector string for the attribute, to be within with JavaScript
     * queries.
     */
    js(value?: NavValue | undefined | ""): string;
    /** Use this to generate a selector for the attribute in CSS. */
    css({ baseSelector, navValue, }?: PartialWithUndefined<{
        baseSelector: string;
        /**
         * Omit this or set to `undefined` or `''` to generate a selector for all elements with the
         * nav attribute.
         */
        navValue: NavValue;
    }>): import("element-vir").CSSResult;
};
/**
 * The property with which {@link NavEntry} instances are attached to elements.
 *
 * @category Internal
 */
export declare const navEntryPropertyKey = "navEntry";
/**
 * Used in type guards to indicate that this object has an attached {@link NavEntry} instance.
 *
 * @category Internal
 */
export type WithNavEntry<T> = T & {
    [navEntryPropertyKey]: NavEntry;
};
/**
 * Checks if the given element has a {@link NavEntry} instance attached to it via
 * {@link navEntryPropertyKey}
 *
 * @category Internal
 */
export declare function hasNavEntry(element: Element): element is WithNavEntry<typeof element>;
/**
 * Params for {@link NavListener}.
 *
 * @category Internal
 */
export type NavListenerParams = {
    enabled: boolean;
    navEntry: NavEntry;
    element: HTMLElement;
    previousNavValue: NavValue | undefined;
};
/**
 * Listener callback for listeners in {@link NavParams}.
 *
 * @category Internal
 */
export type NavListener = (params: NavListenerParams) => MaybePromise<void>;
/**
 * Params for a nav element. This has the following navigation options:
 *
 * - Provide `x` and `y` this element's 2D navigation coordinates.
 * - Provide just `x` to set this element's 1D navigational coordinates.
 * - Set `group: true` to define this element as a group.
 * - Set neither to define this element as a 1D nav entry.
 *
 * @category Internal
 */
export type NavParams = PartialWithUndefined<{
    /**
     * Mark an element as a nav group, which can't receive focus but can define a section of
     * navigable elements.
     */
    group: boolean;
    /** Mark this element's x coordinate, either in 1D or 2D. */
    x: number;
    /**
     * Mark this element's 2 dimensional y coordinate.
     *
     * @default 0
     */
    y: number;
    /** Disable this element's navigation. */
    disabled: boolean;
    listeners: PartialWithUndefined<{
        /** Will be fired when this element is activated. */
        activate: NavListener;
        /** Will be fired when this element is focused. */
        focus: NavListener;
    }>;
}>;
/**
 * Extracts a {@link NavEntry} instance attached to the given element, if it exists, by checking the
 * {@link navEntryPropertyKey} property.
 *
 * @category Internal
 */
export declare function extractNavEntry(element: Element): NavEntry | undefined;
/**
 * A class that is attached to all navigable elements. It is attached to the
 * {@link navEntryPropertyKey} property.
 *
 * @category Internal
 */
export declare class NavEntry {
    readonly element: HTMLElement;
    navParams: Readonly<NavParams>;
    navTreeNode: NavTreeNode | undefined;
    readonly navValue: NavValue | undefined;
    /** Use a singular event listener for all events so it can be removed. */
    protected readonly eventListener: (event: Event) => void;
    protected _navController: NavController | undefined;
    constructor(element: HTMLElement, navController: NavController, navParams: Readonly<NavParams>);
    /** Set the {@link NavController} and add this instance to it. */
    set navController(navController: NavController);
    /** Set the current {@link NavController}. */
    get navController(): NavController;
    /** Clear all nav values from the element, just leave the plain attribute (without a value). */
    clearNavValue(): void;
    /** Focus or blur the element. */
    focus(
    /**
     * - `true` to focus
     * - `false` to unfocus (or "blur")
     */
    enabled: boolean, skipListener?: boolean | undefined): import("../nav-controller/navigate.js").NavigationResult<NavAction.Focus> | undefined;
    /** Activate or deactivate the element. */
    activate(
    /**
     * - `true` to activate
     * - `false` to deactivate
     */
    enabled: boolean): import("../nav-controller/navigate.js").NavigationResult<NavAction.Activate> | undefined;
    /** Set the given {@link NavValue} on the element. */
    protected setNavValue(navValue: NavValue): void;
    /** Remove the given {@link NavValue}, if it exists, from the element. */
    protected removeNavValue(navValue: NavValue): void;
    /** Attach default mouse and focus listeners. */
    protected attachListeners(): void;
}