blockly 12.0.0-beta.4 → 12.0.0-beta.5

package/core/flyout_item.d.ts

@@ -1,32 +1,26 @@
 import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { INavigable } from './interfaces/i_navigable.js';
 /**
  * Representation of an item displayed in a flyout.
  */
 export declare class FlyoutItem {
     private element;
     private type;
-    private focusable;
     /**
      * Creates a new FlyoutItem.
      *
      * @param element The element that will be displayed in the flyout.
      * @param type The type of element. Should correspond to the type of the
      *     flyout inflater that created this object.
-     * @param focusable True if the element should be allowed to be focused by
-     *     e.g. keyboard navigation in the flyout.
      */
-    constructor(element: IBoundedElement, type: string, focusable: boolean);
+    constructor(element: IBoundedElement & INavigable<any>, type: string);
     /**
      * Returns the element displayed in the flyout.
      */
-    getElement(): IBoundedElement;
+    getElement(): IBoundedElement & INavigable<any>;
     /**
      * Returns the type of flyout element this item represents.
      */
     getType(): string;
-    /**
-     * Returns whether or not the flyout element can receive focus.
-     */
-    isFocusable(): boolean;
 }
 //# sourceMappingURL=flyout_item.d.ts.map

package/core/flyout_separator.d.ts

@@ -4,11 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { INavigable } from './interfaces/i_navigable.js';
 import { Rect } from './utils/rect.js';
 /**
  * Representation of a gap between elements in a flyout.
  */
-export declare class FlyoutSeparator implements IBoundedElement {
+export declare class FlyoutSeparator implements IBoundedElement, INavigable<FlyoutSeparator> {
     private gap;
     private axis;
     private x;
@@ -34,6 +35,22 @@ export declare class FlyoutSeparator implements IBoundedElement {
      * @param _reason The reason this move was initiated.
      */
     moveBy(dx: number, dy: number, _reason?: string[]): void;
+    /**
+     * Returns false to prevent this separator from being navigated to by the
+     * keyboard.
+     *
+     * @returns False.
+     */
+    isNavigable(): boolean;
+    /**
+     * Returns this separator's class.
+     *
+     * Used by keyboard navigation to look up the rules for navigating from this
+     * separator.
+     *
+     * @returns This separator's class.
+     */
+    getClass(): typeof FlyoutSeparator;
 }
 /**
  * Representation of an axis along which a separator occupies space.

package/core/focus_manager.d.ts

@@ -49,9 +49,12 @@ export declare class FocusManager {
      * using this constant directly (generally it never should need to be used).
      */
     static readonly PASSIVE_FOCUS_NODE_CSS_CLASS_NAME = "blocklyPassiveFocus";
-    focusedNode: IFocusableNode | null;
-    registeredTrees: Array<IFocusableTree>;
+    private focusedNode;
+    private previouslyFocusedNode;
+    private registeredTrees;
     private currentlyHoldsEphemeralFocus;
+    private lockFocusStateChanges;
+    private recentlyLostAllFocus;
     constructor(addGlobalEventListener: (type: string, listener: EventListener) => void);
     /**
      * Registers a new IFocusableTree for automatic focus management.
@@ -120,17 +123,16 @@ export declare class FocusManager {
      */
     focusTree(focusableTree: IFocusableTree): void;
     /**
-     * Focuses DOM input on the selected node, and marks it as actively focused.
+     * Focuses DOM input on the specified node, and marks it as actively focused.
      *
      * Any previously focused node will be updated to be passively highlighted (if
      * it's in a different focusable tree) or blurred (if it's in the same one).
      *
-     * @param focusableNode The node that should receive active
-     *     focus.
+     * @param focusableNode The node that should receive active focus.
      */
     focusNode(focusableNode: IFocusableNode): void;
     /**
-     * Ephemerally captures focus for a selected element until the returned lambda
+     * Ephemerally captures focus for a specific element until the returned lambda
      * is called. This is expected to be especially useful for ephemeral UI flows
      * like dialogs.
      *
@@ -148,16 +150,82 @@ export declare class FocusManager {
      * simultaneously will result in an error being thrown).
      */
     takeEphemeralFocus(focusableElement: HTMLElement | SVGElement): ReturnEphemeralFocus;
+    /**
+     * Ensures that the manager is currently allowing operations that change its
+     * internal focus state (such as via focusNode()).
+     *
+     * If the manager is currently not allowing state changes, an exception is
+     * thrown.
+     */
+    private ensureManagerIsUnlocked;
+    /**
+     * Updates the internally tracked focused node to the specified node, or null
+     * if focus is being lost. This also updates previous focus tracking.
+     *
+     * @param newFocusedNode The new node to set as focused.
+     */
+    private updateFocusedNode;
+    /**
+     * Defocuses the current actively focused node tracked by the manager, iff
+     * there's a node being tracked and the manager doesn't have ephemeral focus.
+     */
     private defocusCurrentFocusedNode;
-    private setNodeToActive;
-    private setNodeToPassive;
+    /**
+     * Marks the specified node as actively focused, also calling related lifecycle
+     * callback methods for both the node and its parent tree. This ensures that
+     * the node is properly styled to indicate its active focus.
+     *
+     * This does not change the manager's currently tracked node, nor does it
+     * change any other nodes.
+     *
+     * @param node The node to be actively focused.
+     * @param prevTree The tree of the previously actively focused node, or null
+     *     if there wasn't a previously actively focused node.
+     */
+    private activelyFocusNode;
+    /**
+     * Marks the specified node as passively focused, also calling related
+     * lifecycle callback methods for both the node and its parent tree. This
+     * ensures that the node is properly styled to indicate its passive focus.
+     *
+     * This does not change the manager's currently tracked node, nor does it
+     * change any other nodes.
+     *
+     * @param node The node to be passively focused.
+     * @param nextTree The tree of the node receiving active focus, or null if no
+     *     node will be actively focused.
+     */
+    private passivelyFocusNode;
+    /**
+     * Updates the node's styling to indicate that it should have an active focus
+     * indicator.
+     *
+     * @param node The node to be styled for active focus.
+     */
+    private setNodeToVisualActiveFocus;
+    /**
+     * Updates the node's styling to indicate that it should have a passive focus
+     * indicator.
+     *
+     * @param node The node to be styled for passive focus.
+     */
+    private setNodeToVisualPassiveFocus;
+    /**
+     * Removes any active/passive indicators for the specified node.
+     *
+     * @param node The node which should have neither passive nor active focus
+     *     indication.
+     */
     private removeHighlight;
+    private static focusManager;
+    /**
+     * Returns the page-global FocusManager.
+     *
+     * The returned instance is guaranteed to not change across function calls, but
+     * may change across page loads.
+     */
+    static getFocusManager(): FocusManager;
 }
-/**
- * Returns the page-global FocusManager.
- *
- * The returned instance is guaranteed to not change across function calls, but
- * may change across page loads.
- */
+/** Convenience function for FocusManager.getFocusManager. */
 export declare function getFocusManager(): FocusManager;
 //# sourceMappingURL=focus_manager.d.ts.map

package/core/interfaces/i_ast_node_location_svg.d.ts

@@ -8,17 +8,5 @@ import type { IASTNodeLocation } from './i_ast_node_location.js';
  * An AST node location SVG interface.
  */
 export interface IASTNodeLocationSvg extends IASTNodeLocation {
-    /**
-     * Add the marker SVG to this node's SVG group.
-     *
-     * @param markerSvg The SVG root of the marker to be added to the SVG group.
-     */
-    setMarkerSvg(markerSvg: SVGElement | null): void;
-    /**
-     * Add the cursor SVG to this node's SVG group.
-     *
-     * @param cursorSvg The SVG root of the cursor to be added to the SVG group.
-     */
-    setCursorSvg(cursorSvg: SVGElement | null): void;
 }
 //# sourceMappingURL=i_ast_node_location_svg.d.ts.map

package/core/interfaces/i_autohideable.d.ts

@@ -16,4 +16,6 @@ export interface IAutoHideable extends IComponent {
      */
     autoHide(onlyClosePopups: boolean): void;
 }
+/** Returns true if the given object is autohideable. */
+export declare function isAutoHideable(obj: any): obj is IAutoHideable;
 //# sourceMappingURL=i_autohideable.d.ts.map

package/core/interfaces/i_flyout.d.ts

@@ -9,11 +9,12 @@ import type { Coordinate } from '../utils/coordinate.js';
 import type { Svg } from '../utils/svg.js';
 import type { FlyoutDefinition } from '../utils/toolbox.js';
 import type { WorkspaceSvg } from '../workspace_svg.js';
+import { IFocusableTree } from './i_focusable_tree.js';
 import type { IRegistrable } from './i_registrable.js';
 /**
  * Interface for a flyout.
  */
-export interface IFlyout extends IRegistrable {
+export interface IFlyout extends IRegistrable, IFocusableTree {
     /** Whether the flyout is laid out horizontally or not. */
     horizontalLayout: boolean;
     /** Is RTL vs LTR. */

package/core/interfaces/i_focusable_node.d.ts

@@ -23,8 +23,14 @@ export interface IFocusableNode {
      * and a tab index must be present in order for the element to be focusable in
      * the DOM).
      *
-     * It's expected the return element will not change for the lifetime of the
-     * node.
+     * 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).
      */
     getFocusableElement(): HTMLElement | SVGElement;
     /**
@@ -33,5 +39,28 @@ export interface IFocusableNode {
      * belongs.
      */
     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.
+     */
+    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;
 }
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableNode.
+ *
+ * @param object The object to test.
+ * @returns Whether the provided object can be used as an IFocusableNode.
+ */
+export declare function isFocusableNode(object: any | null): object is IFocusableNode;
 //# sourceMappingURL=i_focusable_node.d.ts.map

package/core/interfaces/i_focusable_tree.d.ts

@@ -34,6 +34,35 @@ export interface IFocusableTree {
      * currently have a focused node.
      */
     getRootFocusableNode(): IFocusableNode;
+    /**
+     * Returns the IFocusableNode of this tree that should receive active focus
+     * when the tree itself has focus returned to it.
+     *
+     * There are some very important notes to consider about a tree's focus
+     * lifecycle when implementing a version of this method that doesn't return
+     * null:
+     * 1. A null previousNode does not guarantee first-time focus state as nodes
+     *    can be deleted.
+     * 2. This method is only used when the tree itself is focused, either through
+     *    tab navigation or via FocusManager.focusTree(). In many cases, the
+     *    previously focused node will be directly focused instead which will
+     *    bypass this method.
+     * 3. The default behavior (i.e. returning null here) involves either
+     *    restoring the previous node (previousNode) or focusing the tree's root.
+     * 4. The provided node may sometimes no longer be valid, such as in the case
+     *    an attempt is made to focus a node that has been recently removed from
+     *    its parent tree. Implementations can check for the validity of the node
+     *    in order to specialize the node to which focus should fall back.
+     *
+     * This method is largely intended to provide tree implementations with the
+     * means of specifying a better default node than their root.
+     *
+     * @param previousNode The node that previously held passive focus for this
+     *     tree, or null if the tree hasn't yet been focused.
+     * @returns The IFocusableNode that should now receive focus, or null if
+     *     default behavior should be used, instead.
+     */
+    getRestoredFocusableNode(previousNode: IFocusableNode | null): IFocusableNode | null;
     /**
      * Returns all directly nested trees under this tree.
      *
@@ -54,5 +83,43 @@ export interface IFocusableTree {
      * @param id The ID of the node's focusable HTMLElement or SVGElement.
      */
     lookUpFocusableNode(id: string): IFocusableNode | null;
+    /**
+     * Called when a node of this tree has received active focus.
+     *
+     * Note that a null previousTree does not necessarily indicate that this is
+     * the first time Blockly is receiving focus. In fact, few assumptions can be
+     * made about previous focus state as a previous null tree simply indicates
+     * that Blockly did not hold active focus prior to this tree becoming focused
+     * (which can happen due to focus exiting the Blockly injection div, or for
+     * other cases like ephemeral focus).
+     *
+     * See IFocusableNode.onNodeFocus() as implementations have the same
+     * restrictions as with that method.
+     *
+     * @param node The node receiving active focus.
+     * @param previousTree The previous tree that held active focus, or null if
+     *     none.
+     */
+    onTreeFocus(node: IFocusableNode, previousTree: IFocusableTree | null): void;
+    /**
+     * Called when the previously actively focused node of this tree is now
+     * passively focused and there is no other active node of this tree taking its
+     * place.
+     *
+     * This has the same implementation restrictions and considerations as
+     * onTreeFocus().
+     *
+     * @param nextTree The next tree receiving active focus, or null if none (such
+     *     as in the case that Blockly is entirely losing DOM focus).
+     */
+    onTreeBlur(nextTree: IFocusableTree | null): void;
 }
+/**
+ * Determines whether the provided object fulfills the contract of
+ * IFocusableTree.
+ *
+ * @param object The object to test.
+ * @returns Whether the provided object can be used as an IFocusableTree.
+ */
+export declare function isFocusableTree(object: any | null): object is IFocusableTree;
 //# sourceMappingURL=i_focusable_tree.d.ts.map

package/core/interfaces/i_navigable.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Represents a UI element which can be navigated to using the keyboard.
+ */
+export interface INavigable<T> {
+    /**
+     * Returns whether or not this specific instance should be reachable via
+     * keyboard navigation.
+     *
+     * Implementors should generally return true, unless there are circumstances
+     * under which this item should be skipped while using keyboard navigation.
+     * Common examples might include being disabled, invalid, readonly, or purely
+     * a visual decoration. For example, while Fields are navigable, non-editable
+     * fields return false, since they cannot be interacted with when focused.
+     *
+     * @returns True if this element should be included in keyboard navigation.
+     */
+    isNavigable(): boolean;
+    /**
+     * Returns the class of this instance.
+     *
+     * @returns This object's class.
+     */
+    getClass(): new (...args: any) => T;
+}
+//# sourceMappingURL=i_navigable.d.ts.map

package/core/interfaces/i_navigation_policy.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { INavigable } from './i_navigable.js';
+/**
+ * A set of rules that specify where keyboard navigation should proceed.
+ */
+export interface INavigationPolicy<T> {
+    /**
+     * Returns the first child element of the given element, if any.
+     *
+     * @param current The element which the user is navigating into.
+     * @returns The current element's first child, or null if it has none.
+     */
+    getFirstChild(current: T): INavigable<any> | null;
+    /**
+     * Returns the parent element of the given element, if any.
+     *
+     * @param current The element which the user is navigating out of.
+     * @returns The parent element of the current element, or null if it has none.
+     */
+    getParent(current: T): INavigable<any> | null;
+    /**
+     * Returns the peer element following the given element, if any.
+     *
+     * @param current The element which the user is navigating past.
+     * @returns The next peer element of the current element, or null if there is
+     *     none.
+     */
+    getNextSibling(current: T): INavigable<any> | null;
+    /**
+     * Returns the peer element preceding the given element, if any.
+     *
+     * @param current The element which the user is navigating past.
+     * @returns The previous peer element of the current element, or null if
+     *     there is none.
+     */
+    getPreviousSibling(current: T): INavigable<any> | null;
+}
+//# sourceMappingURL=i_navigation_policy.d.ts.map

package/core/interfaces/i_toolbox.d.ts

@@ -6,12 +6,13 @@
 import type { ToolboxInfo } from '../utils/toolbox.js';
 import type { WorkspaceSvg } from '../workspace_svg.js';
 import type { IFlyout } from './i_flyout.js';
+import type { IFocusableTree } from './i_focusable_tree.js';
 import type { IRegistrable } from './i_registrable.js';
 import type { IToolboxItem } from './i_toolbox_item.js';
 /**
  * Interface for a toolbox.
  */
-export interface IToolbox extends IRegistrable {
+export interface IToolbox extends IRegistrable, IFocusableTree {
     /** Initializes the toolbox. */
     init(): void;
     /**

package/core/interfaces/i_toolbox_item.d.ts

@@ -3,10 +3,11 @@
  * Copyright 2020 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import type { IFocusableNode } from './i_focusable_node.js';
 /**
  * Interface for an item in the toolbox.
  */
-export interface IToolboxItem {
+export interface IToolboxItem extends IFocusableNode {
     /**
      * Initializes the toolbox item.
      * This includes creating the DOM and updating the state of any items based

package/core/keyboard_nav/ast_node.d.ts

@@ -80,89 +80,7 @@ export declare class ASTNode {
      * @internal
      */
     isConnection(): boolean;
-    /**
-     * Given an input find the next editable field or an input with a non null
-     * connection in the same block. The current location must be an input
-     * connection.
-     *
-     * @returns The AST node holding the next field or connection or null if there
-     *     is no editable field or input connection after the given input.
-     */
-    private findNextForInput;
-    /**
-     * Given a field find the next editable field or an input with a non null
-     * connection in the same block. The current location must be a field.
-     *
-     * @returns The AST node pointing to the next field or connection or null if
-     *     there is no editable field or input connection after the given input.
-     */
-    private findNextForField;
-    /**
-     * Given an input find the previous editable field or an input with a non null
-     * connection in the same block. The current location must be an input
-     * connection.
-     *
-     * @returns The AST node holding the previous field or connection.
-     */
-    private findPrevForInput;
-    /**
-     * Given a field find the previous editable field or an input with a non null
-     * connection in the same block. The current location must be a field.
-     *
-     * @returns The AST node holding the previous input or field.
-     */
-    private findPrevForField;
-    /**
-     * Navigate between stacks of blocks on the workspace.
-     *
-     * @param forward True to go forward. False to go backwards.
-     * @returns The first block of the next stack or null if there are no blocks
-     *     on the workspace.
-     */
-    private navigateBetweenStacks;
-    /**
-     * Navigate between buttons and stacks of blocks on the flyout workspace.
-     *
-     * @param forward True to go forward. False to go backwards.
-     * @returns The next button, or next stack's first block, or null
-     */
-    private navigateFlyoutContents;
-    /**
-     * Finds the next (or previous if navigating backward) item in the flyout that should be navigated to.
-     *
-     * @param flyoutContents Contents of the current flyout.
-     * @param currentLocation Current ASTNode location.
-     * @param forward True if we're navigating forward, else false.
-     * @returns The next (or previous) FlyoutItem, or null if there is none.
-     */
-    private findNextLocationInFlyout;
-    /**
-     * Finds the top most AST node for a given block.
-     * This is either the previous connection, output connection or block
-     * depending on what kind of connections the block has.
-     *
-     * @param block The block that we want to find the top connection on.
-     * @returns The AST node containing the top connection.
-     */
-    private findTopASTNodeForBlock;
-    /**
-     * Get the AST node pointing to the input that the block is nested under or if
-     * the block is not nested then get the stack AST node.
-     *
-     * @param block The source block of the current location.
-     * @returns The AST node pointing to the input connection or the top block of
-     *     the stack this block is in.
-     */
-    private getOutAstNodeForBlock;
-    /**
-     * Find the first editable field or input with a connection on a given block.
-     *
-     * @param block The source block of the current location.
-     * @returns An AST node pointing to the first field or input.
-     * Null if there are no editable fields or inputs with connections on the
-     * block.
-     */
-    private findFirstFieldOrInput;
+    private getVisibleInputs;
     /**
      * Finds the source block of the location of this node.
      *
@@ -170,36 +88,6 @@ export declare class ASTNode {
      *     workspace or button.
      */
     getSourceBlock(): Block | null;
-    /**
-     * Find the element to the right of the current element in the AST.
-     *
-     * @returns An AST node that wraps the next field, connection, block, or
-     *     workspace. Or null if there is no node to the right.
-     */
-    next(): ASTNode | null;
-    /**
-     * Find the element one level below and all the way to the left of the current
-     * location.
-     *
-     * @returns An AST node that wraps the next field, connection, workspace, or
-     *     block. Or null if there is nothing below this node.
-     */
-    in(): ASTNode | null;
-    /**
-     * Find the element to the left of the current element in the AST.
-     *
-     * @returns An AST node that wraps the previous field, connection, workspace
-     *     or block. Or null if no node exists to the left. null.
-     */
-    prev(): ASTNode | null;
-    /**
-     * Find the next element that is one position above and all the way to the
-     * left of the current location.
-     *
-     * @returns An AST node that wraps the next field, connection, workspace or
-     *     block. Or null if we are at the workspace level.
-     */
-    out(): ASTNode | null;
     /**
      * Whether an AST node of the given type points to a connection.
      *

package/core/keyboard_nav/block_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BlockSvg } from '../block_svg.js';
+import type { INavigable } from '../interfaces/i_navigable.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+import type { RenderedConnection } from '../rendered_connection.js';
+/**
+ * Set of rules controlling keyboard navigation from a block.
+ */
+export declare class BlockNavigationPolicy implements INavigationPolicy<BlockSvg> {
+    /**
+     * Returns the first child of the given block.
+     *
+     * @param current The block to return the first child of.
+     * @returns The first field or input of the given block, if any.
+     */
+    getFirstChild(current: BlockSvg): INavigable<unknown> | null;
+    /**
+     * Returns the parent of the given block.
+     *
+     * @param current The block to return the parent of.
+     * @returns The top block of the given block's stack, or the connection to
+     *     which it is attached.
+     */
+    getParent(current: BlockSvg): INavigable<unknown> | null;
+    /**
+     * Returns the next peer node of the given block.
+     *
+     * @param current The block to find the following element of.
+     * @returns The first block of the next stack if the given block is a terminal
+     *     block, or its next connection.
+     */
+    getNextSibling(current: BlockSvg): INavigable<unknown> | null;
+    /**
+     * Returns the previous peer node of the given block.
+     *
+     * @param current The block to find the preceding element of.
+     * @returns The block's previous/output connection, or the last
+     *     connection/block of the previous block stack if it is a root block.
+     */
+    getPreviousSibling(current: BlockSvg): INavigable<unknown> | null;
+    /**
+     * Gets the parent connection on a block.
+     * This is either an output connection, previous connection or undefined.
+     * If both connections exist return the one that is actually connected
+     * to another block.
+     *
+     * @param block The block to find the parent connection on.
+     * @returns The connection connecting to the parent of the block.
+     */
+    protected getParentConnection(block: BlockSvg): RenderedConnection;
+}
+//# sourceMappingURL=block_navigation_policy.d.ts.map