blockly 12.0.0-beta.3 → 12.0.0-beta.5

package/core/flyout_base.d.ts

@@ -14,6 +14,8 @@ import { FlyoutItem } from './flyout_item.js';
 import { IAutoHideable } from './interfaces/i_autohideable.js';
 import type { IFlyout } from './interfaces/i_flyout.js';
 import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
+import { IFocusableNode } from './interfaces/i_focusable_node.js';
+import { IFocusableTree } from './interfaces/i_focusable_tree.js';
 import type { Options } from './options.js';
 import * as blocks from './serialization/blocks.js';
 import { Coordinate } from './utils/coordinate.js';
@@ -23,7 +25,7 @@ import { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a flyout.
  */
-export declare abstract class Flyout extends DeleteArea implements IAutoHideable, IFlyout {
+export declare abstract class Flyout extends DeleteArea implements IAutoHideable, IFlyout, IFocusableNode {
     /**
      * Position the flyout.
      */
@@ -399,5 +401,25 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      *     is registered for that type.
      */
     protected getInflaterForType(type: string): IFlyoutInflater | null;
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /** See IFocusableTree.getRootFocusableNode. */
+    getRootFocusableNode(): IFocusableNode;
+    /** See IFocusableTree.getRestoredFocusableNode. */
+    getRestoredFocusableNode(_previousNode: IFocusableNode | null): IFocusableNode | null;
+    /** See IFocusableTree.getNestedTrees. */
+    getNestedTrees(): Array<IFocusableTree>;
+    /** See IFocusableTree.lookUpFocusableNode. */
+    lookUpFocusableNode(_id: string): IFocusableNode | null;
+    /** See IFocusableTree.onTreeFocus. */
+    onTreeFocus(_node: IFocusableNode, _previousTree: IFocusableTree | null): void;
+    /** See IFocusableTree.onTreeBlur. */
+    onTreeBlur(nextTree: IFocusableTree | null): void;
 }
 //# sourceMappingURL=flyout_base.d.ts.map

package/core/flyout_button.d.ts

@@ -10,6 +10,9 @@
  */
 import type { IASTNodeLocationSvg } from './blockly.js';
 import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+import type { INavigable } from './interfaces/i_navigable.js';
 import type { IRenderedElement } from './interfaces/i_rendered_element.js';
 import { Coordinate } from './utils/coordinate.js';
 import { Rect } from './utils/rect.js';
@@ -18,7 +21,7 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for a button or label in the flyout.
  */
-export declare class FlyoutButton implements IASTNodeLocationSvg, IBoundedElement, IRenderedElement {
+export declare class FlyoutButton implements IASTNodeLocationSvg, IBoundedElement, IRenderedElement, IFocusableNode, INavigable<FlyoutButton> {
     private readonly workspace;
     private readonly targetWorkspace;
     private readonly isFlyoutLabel;
@@ -49,6 +52,8 @@ export declare class FlyoutButton implements IASTNodeLocationSvg, IBoundedElemen
      * This is null if there is no cursor on the button.
      */
     cursorSvg: SVGElement | null;
+    /** The unique ID for this FlyoutButton. */
+    private id;
     /**
      * @param workspace The workspace in which to place this button.
      * @param targetWorkspace The flyout's target workspace.
@@ -116,12 +121,6 @@ export declare class FlyoutButton implements IASTNodeLocationSvg, IBoundedElemen
      *     group.
      */
     setCursorSvg(cursorSvg: SVGElement): void;
-    /**
-     * Required by IASTNodeLocationSvg, but not used. A marker cannot be set on a
-     * button. If the 'mark' shortcut is used on a button, its associated callback
-     * function is triggered.
-     */
-    setMarkerSvg(): void;
     /**
      * Do something when the button is clicked.
      *
@@ -133,5 +132,29 @@ export declare class FlyoutButton implements IASTNodeLocationSvg, IBoundedElemen
      * @returns The root SVG element of this rendered element.
      */
     getSvgRoot(): SVGGElement;
+    /** See IFocusableNode.getFocusableElement. */
+    getFocusableElement(): HTMLElement | SVGElement;
+    /** See IFocusableNode.getFocusableTree. */
+    getFocusableTree(): IFocusableTree;
+    /** See IFocusableNode.onNodeFocus. */
+    onNodeFocus(): void;
+    /** See IFocusableNode.onNodeBlur. */
+    onNodeBlur(): void;
+    /**
+     * Returns whether or not this button is accessible through keyboard
+     * navigation.
+     *
+     * @returns True if this button is keyboard accessible, otherwise false.
+     */
+    isNavigable(): boolean;
+    /**
+     * Returns this button's class.
+     *
+     * Used by keyboard navigation to look up the rules for navigating from this
+     * button.
+     *
+     * @returns This button's class.
+     */
+    getClass(): typeof FlyoutButton;
 }
 //# sourceMappingURL=flyout_button.d.ts.map

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