blockly
Version:
Blockly is a library for building visual programming editors.
105 lines • 5.04 kB
TypeScript
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import type { IFocusableTree } from './i_focusable_tree.js';
/** Represents anything that can have input focus. */
export interface IFocusableNode {
/**
* Returns the DOM element that can be explicitly requested to receive focus.
*
* IMPORTANT: Please note that this element is expected to have a visual
* presence on the page as it will both be explicitly focused and have its
* style changed depending on its current focus state (i.e. blurred, actively
* focused, and passively focused). The element will have one of two styles
* attached (where no style indicates blurred/not focused):
* - blocklyActiveFocus
* - blocklyPassiveFocus
*
* The returned element must also have a valid ID specified, and this ID
* should be unique across the entire page. Failing to have a properly unique
* ID could result in trying to focus one node (such as via a mouse click)
* leading to another node with the same ID actually becoming focused by
* FocusManager.
*
* The returned element must be visible if the node is ever focused via
* FocusManager.focusNode() or FocusManager.focusTree(). It's allowed for an
* element to be hidden until onNodeFocus() is called, or become hidden with a
* call to onNodeBlur().
*
* It's expected the actual returned element will not change for the lifetime
* of the node (that is, its properties can change but a new element should
* never be returned). Also, the returned element will have its tabindex
* overwritten throughout the lifecycle of this node and FocusManager.
*
* If a node requires the ability to be focused directly without first being
* focused via FocusManager then it must set its own tab index.
*
* @returns The HTMLElement or SVGElement which can both receive focus and be
* visually represented as actively or passively focused for this node.
*/
getFocusableElement(): HTMLElement | SVGElement;
/**
* Returns the closest parent tree of this node (in cases where a tree has
* distinct trees underneath it), which represents the tree to which this node
* belongs.
*
* @returns The node's IFocusableTree.
*/
getFocusableTree(): IFocusableTree;
/**
* Called when this node receives active focus.
*
* Note that it's fine for implementations to change visibility modifiers, but
* they should avoid the following:
* - Creating or removing DOM elements (including via the renderer or drawer).
* - Affecting focus via DOM focus() calls or the FocusManager.
*
* Implementations may consider scrolling themselves into view here; that is
* not handled by the focus manager.
*/
onNodeFocus(): void;
/**
* Called when this node loses active focus. It may still have passive focus.
*
* This has the same implementation restrictions as onNodeFocus().
*/
onNodeBlur(): void;
/**
* Indicates whether this node allows focus. If this returns false then none
* of the other IFocusableNode methods will be called.
*
* Note that special care must be taken if implementations of this function
* dynamically change their return value value over the lifetime of the node
* as certain environment conditions could affect the focusability of this
* node's DOM element (such as whether the element has a positive or zero
* tabindex). Also, changing from a true to a false value while the node holds
* focus will not immediately change the current focus of the node nor
* FocusManager's internal state, and thus may result in some of the node's
* functions being called later on when defocused (since it was previously
* considered focusable at the time of being focused).
*
* Implementations should generally always return true here unless there are
* circumstances under which this node should be skipped for focus
* considerations. Examples may include being disabled, read-only, a purely
* visual decoration, or a node with no visual representation that must
* implement this interface (e.g. due to a parent interface extending it).
* Keep in mind accessibility best practices when determining whether a node
* should be focusable since even disabled and read-only elements are still
* often relevant to providing organizational context to users (particularly
* when using a screen reader).
*
* @returns Whether this node can be focused by FocusManager.
*/
canBeFocused(): boolean;
}
/**
* Determines whether the provided object fulfills the contract of
* IFocusableNode.
*
* @param obj The object to test.
* @returns Whether the provided object can be used as an IFocusableNode.
*/
export declare function isFocusableNode(obj: any): obj is IFocusableNode;
//# sourceMappingURL=i_focusable_node.d.ts.map