@difizen/mana-core/es/view/focus-tracker.d.ts

import type { Disposable, Event as EmitterEvent } from '@difizen/mana-common';
import { Emitter } from '@difizen/mana-common';
import type { View } from './view-protocol';
/**
 * A class which tracks focus among a set of views.
 *
 * This class is useful when code needs to keep track of the most
 * recently focused view(s) among a set of related views.
 */
export declare class FocusTracker<T extends View> implements Disposable {
    protected counter: number;
    protected _views: T[];
    protected _activeView: T | null;
    protected _currentView: T | null;
    protected numbers: Map<T, number>;
    protected nodes: Map<HTMLElement, T>;
    protected activeChangedEmitter: Emitter<FocusTracker.IChangedArgs<T>>;
    protected currentChangedEmitter: Emitter<FocusTracker.IChangedArgs<T>>;
    /**
     * A signal emitted when the current view has changed.
     */
    get currentChanged(): EmitterEvent<FocusTracker.IChangedArgs<T>>;
    /**
     * A signal emitted when the active view has changed.
     */
    get activeChanged(): EmitterEvent<FocusTracker.IChangedArgs<T>>;
    /**
     * A flag indicating whether the tracker is disposed.
     */
    get isDisposed(): boolean;
    /**
     * The current view in the tracker.
     *
     * #### Notes
     * The current view is the view among the tracked views which
     * has the *descendant node* which has most recently been focused.
     *
     * The current view will not be updated if the node loses focus. It
     * will only be updated when a different tracked view gains focus.
     *
     * If the current view is removed from the tracker, the previous
     * current view will be restored.
     *
     * This behavior is intended to follow a user's conceptual model of
     * a semantically "current" view, where the "last thing of type X"
     * to be interacted with is the "current instance of X", regardless
     * of whether that instance still has focus.
     */
    get currentView(): T | null;
    /**
     * The active view in the tracker.
     *
     * #### Notes
     * The active view is the view among the tracked views which
     * has the *descendant node* which is currently focused.
     */
    get activeView(): T | null;
    /**
     * A read only array of the views being tracked.
     */
    get views(): readonly T[];
    /**
     * Dispose of the resources held by the tracker.
     */
    dispose(): void;
    /**
     * Get the focus number for a particular view in the tracker.
     *
     * @param view - The view of interest.
     *
     * @returns The focus number for the given view, or `-1` if the
     *   view has not had focus since being added to the tracker, or
     *   is not contained by the tracker.
     *
     * #### Notes
     * The focus number indicates the relative order in which the views
     * have gained focus. A view with a larger number has gained focus
     * more recently than a view with a smaller number.
     *
     * The `currentView` will always have the largest focus number.
     *
     * All views start with a focus number of `-1`, which indicates that
     * the view has not been focused since being added to the tracker.
     */
    focusNumber(view: T): number;
    /**
     * Test whether the focus tracker contains a given view.
     *
     * @param view - The view of interest.
     *
     * @returns `true` if the view is tracked, `false` otherwise.
     */
    has(view: T): boolean;
    /**
     * Add a view to the focus tracker.
     *
     * @param view - The view of interest.
     *
     * #### Notes
     * A view will be automatically removed from the tracker if it
     * is disposed after being added.
     *
     * If the view is already tracked, this is a no-op.
     */
    add(view: T): void;
    /**
     * Remove a view from the focus tracker.
     *
     * #### Notes
     * If the view is the `currentView`, the previous current view
     * will become the new `currentView`.
     *
     * A view will be automatically removed from the tracker if it
     * is disposed after being added.
     *
     * If the view is not tracked, this is a no-op.
     */
    remove(view: T): void;
    /**
     * Handle the DOM events for the focus tracker.
     *
     * @param event - The DOM event sent to the panel.
     *
     * #### Notes
     * This method implements the DOM `EventListener` interface and is
     * called in response to events on the tracked nodes. It should
     * not be called directly by user code.
     */
    handleEvent(event: Event): void;
    /**
     * Set the current and active views for the tracker.
     */
    protected setViews(current: T | null, active: T | null): void;
    /**
     * Handle the `'focus'` event for a tracked view.
     */
    protected handleFocusEvent(event: FocusEvent): void;
    /**
     * Handle the `'blur'` event for a tracked view.
     */
    protected handleBlurEvent(event: FocusEvent): void;
    /**
     * Handle the `disposed` signal for a tracked view.
     */
    protected onViewDisposed(sender: T): void;
}
/**
 * The namespace for the `FocusTracker` class statics.
 */
export declare namespace FocusTracker {
    /**
     * An arguments object for the changed signals.
     */
    interface IChangedArgs<T extends View> {
        /**
         * The old value for the view.
         */
        oldValue: T | null;
        /**
         * The new value for the view.
         */
        newValue: T | null;
    }
}
//# sourceMappingURL=focus-tracker.d.ts.map