@loadsmart/miranda-wc/dist/controllers/focus-manager/focus-manager.controller.d.ts

Miranda Web Components component library

import type { ReactiveControllerHost, ReactiveController } from 'lit';
export declare const SEARCH_BUFFER_TIMEOUT = 500;
export type FocusManagerControllerHost = ReactiveControllerHost & HTMLElement;
export type FocusManagerControllerOptions<T> = {
    query: string | string[] | ((host: FocusManagerControllerHost) => T[]);
    focusOnType?: boolean;
    getInteractiveElement?: (host: FocusManagerControllerHost) => HTMLElement;
};
export type PositionalFocus = 'first' | 'last' | 'previous' | 'next';
/**
 * Check if `keyboardEventKey` is a character, and more specifically, anything
 * other than a space, tab, or newline.
 */
export declare function isPrintableCharacter(keyboardEventKey: string): boolean;
/**
 * Manages **virtual/visual** focus, for a11y purposes.
 */
export declare class FocusManagerController<T extends HTMLElement = HTMLElement> implements ReactiveController {
    #private;
    host: FocusManagerControllerHost;
    activeDescendant: string | null;
    /**
     * Keys (printable characters) the user typed on the watched host.
     * The expectation is that the user wants to focus/select something.
     */
    quickSearchBuffer: string;
    /**
     * Timeout to clear the buffer.
     */
    quickSearchBufferTimeout?: number | null;
    /**
     * Query to get virtually focusable elements inside the `host`.
     */
    query: string | ((host: FocusManagerControllerHost) => T[]);
    /**
     * When user types printable characters, should the focus move to the next `queried` item whose label
     * starts with `quickSearchBuffer`, if such an item exists (otherwise, focus does not move)?
     */
    focusOnType: boolean;
    /**
     * Get the element that will receive the `aria-activedescendant` attribute. This is necessary when the
     * host element is not the one directly hosting the focusable elements.
     * If no override is provided, the `host` element itself is used.
     *
     * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-activedescendant MDN, aria-activedescendant}
     */
    getInteractiveElement: (host: FocusManagerControllerHost) => HTMLElement;
    constructor(host: FocusManagerControllerHost, options: FocusManagerControllerOptions<T>);
    hostConnected(): void;
    hostDisconnected(): void;
    /**
     * Get the list of elements matching the given `options.query`.
     */
    get queried(): T[];
    /**
     * Get the currently focused element, based on `activeDescendant`.
     */
    get focused(): T | null;
    /**
     * If none of the options are selected, the first option receives focus; otherwise, the
     * focus moves to the next option.
     * If we are at the end of the `queried` array, the focus moves to the first option.
     */
    focusNext(): void;
    /**
     * If none of the options are selected, the last option receives focus; otherwise, the
     * focus moves to the next option.
     * If we are at the start of the `queried` array, the focus moves to the last option.
     */
    focusPrevious(): void;
    /**
     * Focus the first element in `queried`.
     */
    focusFirst(): void;
    /**
     * Focus the last element in `queried`.
     */
    focusLast(): void;
    /**
     * Focus the given element or the element at the given index or position, based on `queried`.
     */
    focus(where: number | HTMLElement | PositionalFocus): void;
    /**
     * Remove the visual focus (`.is-focused` class) from the currently focused element and
     * clear the `activeDescendant` attribute.
     */
    clear(): void;
}