blockly 12.0.0 → 12.1.0-beta.0

package/core/blockly.d.ts

@@ -106,6 +106,7 @@ import { IVariableMap } from './interfaces/i_variable_map.js';
 import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import { LineCursor } from './keyboard_nav/line_cursor.js';
 import { Marker } from './keyboard_nav/marker.js';
+import { KeyboardNavigationController, keyboardNavigationController } from './keyboard_navigation_controller.js';
 import type { LayerManager } from './layer_manager.js';
 import * as layers from './layers.js';
 import { MarkerManager } from './marker_manager.js';
@@ -281,5 +282,5 @@ export * from './navigator.js';
 export * from './toast.js';
 export { Block, BlockSvg, BlocklyOptions, Blocks, CollapsibleToolboxCategory, ComponentManager, Connection, ConnectionChecker, ConnectionDB, ConnectionType, ContextMenu, ContextMenuItems, ContextMenuRegistry, Css, DeleteArea, DragTarget, Events, Extensions, LineCursor, Procedures, ShortcutItems, Themes, Tooltip, Touch, Variables, VariablesDynamic, WidgetDiv, Xml, blockAnimations, blockRendering, browserEvents, bubbles, bumpObjects, clipboard, comments, common, constants, dialog, dragging, fieldRegistry, geras, Procedures as procedures, registry, thrasos, uiPosition, utils, zelos, };
 export declare const DropDownDiv: typeof dropDownDiv;
-export { BlockFlyoutInflater, ButtonFlyoutInflater, CodeGenerator, Field, FieldCheckbox, FieldCheckboxConfig, FieldCheckboxFromJsonConfig, FieldCheckboxValidator, FieldConfig, FieldDropdown, FieldDropdownConfig, FieldDropdownFromJsonConfig, FieldDropdownValidator, FieldImage, FieldImageConfig, FieldImageFromJsonConfig, FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig, FieldLabelSerializable, FieldNumber, FieldNumberConfig, FieldNumberFromJsonConfig, FieldNumberValidator, FieldTextInput, FieldTextInputConfig, FieldTextInputFromJsonConfig, FieldTextInputValidator, FieldValidator, FieldVariable, FieldVariableConfig, FieldVariableFromJsonConfig, FieldVariableValidator, Flyout, FlyoutButton, FlyoutItem, FlyoutMetricsManager, FlyoutSeparator, FocusManager, FocusableTreeTraverser, CodeGenerator as Generator, Gesture, Grid, HorizontalFlyout, IAutoHideable, IBoundedElement, IBubble, ICollapsibleToolboxItem, IComponent, IConnectionChecker, IConnectionPreviewer, IContextMenu, ICopyData, ICopyable, IDeletable, IDeleteArea, IDragStrategy, IDragTarget, IDraggable, IDragger, IFlyout, IFlyoutInflater, IFocusableNode, IFocusableTree, IHasBubble, IIcon, IKeyboardAccessible, IMetricsManager, IMovable, IObservable, IPaster, IPositionable, IRegistrable, IRenderedElement, ISelectable, ISelectableToolboxItem, ISerializable, IStyleable, IToolbox, IToolboxItem, IVariableBackedParameterModel, IVariableMap, IVariableModel, IVariableState, ImageProperties, Input, InsertionMarkerPreviewer, LabelFlyoutInflater, LayerManager, Marker, MarkerManager, Menu, MenuGenerator, MenuGeneratorFunction, MenuItem, MenuOption, MetricsManager, Msg, Names, Options, RenderedConnection, ReturnEphemeralFocus, Scrollbar, ScrollbarPair, SeparatorFlyoutInflater, ShortcutRegistry, Theme, ThemeManager, Toolbox, ToolboxCategory, ToolboxItem, ToolboxSeparator, Trashcan, UnattachedFieldError, VariableMap, VariableModel, VerticalFlyout, Workspace, WorkspaceAudio, WorkspaceDragger, WorkspaceSvg, ZoomControls, config, getFocusManager, hasBubble, icons, inject, inputs, isCopyable, isDeletable, isDraggable, isIcon, isObservable, isPaster, isRenderedElement, isSelectable, isSerializable, isVariableBackedParameterModel, layers, renderManagement, serialization, setLocale, };
+export { BlockFlyoutInflater, ButtonFlyoutInflater, CodeGenerator, Field, FieldCheckbox, FieldCheckboxConfig, FieldCheckboxFromJsonConfig, FieldCheckboxValidator, FieldConfig, FieldDropdown, FieldDropdownConfig, FieldDropdownFromJsonConfig, FieldDropdownValidator, FieldImage, FieldImageConfig, FieldImageFromJsonConfig, FieldLabel, FieldLabelConfig, FieldLabelFromJsonConfig, FieldLabelSerializable, FieldNumber, FieldNumberConfig, FieldNumberFromJsonConfig, FieldNumberValidator, FieldTextInput, FieldTextInputConfig, FieldTextInputFromJsonConfig, FieldTextInputValidator, FieldValidator, FieldVariable, FieldVariableConfig, FieldVariableFromJsonConfig, FieldVariableValidator, Flyout, FlyoutButton, FlyoutItem, FlyoutMetricsManager, FlyoutSeparator, FocusManager, FocusableTreeTraverser, CodeGenerator as Generator, Gesture, Grid, HorizontalFlyout, IAutoHideable, IBoundedElement, IBubble, ICollapsibleToolboxItem, IComponent, IConnectionChecker, IConnectionPreviewer, IContextMenu, ICopyData, ICopyable, IDeletable, IDeleteArea, IDragStrategy, IDragTarget, IDraggable, IDragger, IFlyout, IFlyoutInflater, IFocusableNode, IFocusableTree, IHasBubble, IIcon, IKeyboardAccessible, IMetricsManager, IMovable, IObservable, IPaster, IPositionable, IRegistrable, IRenderedElement, ISelectable, ISelectableToolboxItem, ISerializable, IStyleable, IToolbox, IToolboxItem, IVariableBackedParameterModel, IVariableMap, IVariableModel, IVariableState, ImageProperties, Input, InsertionMarkerPreviewer, KeyboardNavigationController, LabelFlyoutInflater, LayerManager, Marker, MarkerManager, Menu, MenuGenerator, MenuGeneratorFunction, MenuItem, MenuOption, MetricsManager, Msg, Names, Options, RenderedConnection, ReturnEphemeralFocus, Scrollbar, ScrollbarPair, SeparatorFlyoutInflater, ShortcutRegistry, Theme, ThemeManager, Toolbox, ToolboxCategory, ToolboxItem, ToolboxSeparator, Trashcan, UnattachedFieldError, VariableMap, VariableModel, VerticalFlyout, Workspace, WorkspaceAudio, WorkspaceDragger, WorkspaceSvg, ZoomControls, config, getFocusManager, hasBubble, icons, inject, inputs, isCopyable, isDeletable, isDraggable, isIcon, isObservable, isPaster, isRenderedElement, isSelectable, isSerializable, isVariableBackedParameterModel, keyboardNavigationController, layers, renderManagement, serialization, setLocale, };
 //# sourceMappingURL=blockly.d.ts.map

package/core/bubbles/bubble.d.ts

@@ -70,8 +70,8 @@ export declare abstract class Bubble implements IBubble, ISelectable {
      *     when automatically positioning.
      * @param overriddenFocusableElement An optional replacement to the focusable
      *     element that's represented by this bubble (as a focusable node). This
-     *     element will have its ID and tabindex overwritten. If not provided, the
-     *     focusable element of this node will default to the bubble's SVG root.
+     *     element will have its ID overwritten. If not provided, the focusable
+     *     element of this node will default to the bubble's SVG root.
      */
     constructor(workspace: WorkspaceSvg, anchor: Coordinate, ownerRect?: Rect | undefined, overriddenFocusableElement?: SVGElement | HTMLElement);
     /** Dispose of this bubble. */

package/core/comments/rendered_workspace_comment.d.ts

@@ -9,6 +9,7 @@ import { IContextMenu } from '../interfaces/i_contextmenu.js';
 import { ICopyable } from '../interfaces/i_copyable.js';
 import { IDeletable } from '../interfaces/i_deletable.js';
 import { IDraggable } from '../interfaces/i_draggable.js';
+import { IFocusableNode } from '../interfaces/i_focusable_node.js';
 import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
 import { IRenderedElement } from '../interfaces/i_rendered_element.js';
 import { ISelectable } from '../interfaces/i_selectable.js';
@@ -17,7 +18,7 @@ import { Rect } from '../utils/rect.js';
 import { Size } from '../utils/size.js';
 import { WorkspaceSvg } from '../workspace_svg.js';
 import { WorkspaceComment } from './workspace_comment.js';
-export declare class RenderedWorkspaceComment extends WorkspaceComment implements IBoundedElement, IRenderedElement, IDraggable, ISelectable, IDeletable, ICopyable<WorkspaceCommentCopyData>, IContextMenu {
+export declare class RenderedWorkspaceComment extends WorkspaceComment implements IBoundedElement, IRenderedElement, IDraggable, ISelectable, IDeletable, ICopyable<WorkspaceCommentCopyData>, IContextMenu, IFocusableNode {
     /** The class encompassing the svg elements making up the workspace comment. */
     private view;
     readonly workspace: WorkspaceSvg;

package/core/common.d.ts

@@ -148,6 +148,14 @@ export declare function createBlockDefinitionsFromJsonArray(jsonArray: any[]): {
 export declare function defineBlocks(blocks: {
     [key: string]: BlockDefinition;
 }): void;
+/**
+ * Handle a key-down on SVG drawing surface. Does nothing if the main workspace
+ * is not visible.
+ *
+ * @internal
+ * @param e Key down event.
+ */
+export declare function globalShortcutHandler(e: KeyboardEvent): void;
 export declare const TEST_ONLY: {
     defineBlocksWithJsonArrayInternal: typeof defineBlocksWithJsonArrayInternal;
 };

package/core/dropdowndiv.d.ts

@@ -95,9 +95,14 @@ export declare function setColour(backgroundColour: string, borderColour: string
  * @param block Block to position the drop-down around.
  * @param opt_onHide Optional callback for when the drop-down is hidden.
  * @param opt_secondaryYOffset Optional Y offset for above-block positioning.
+ * @param manageEphemeralFocus Whether ephemeral focus should be managed
+ *     according to the drop-down div's lifetime. Note that if a false value is
+ *     passed in here then callers should manage ephemeral focus directly
+ *     otherwise focus may not properly restore when the widget closes. Defaults
+ *     to true.
  * @returns True if the menu rendered below block; false if above.
  */
-export declare function showPositionedByBlock<T>(field: Field<T>, block: BlockSvg, opt_onHide?: () => void, opt_secondaryYOffset?: number): boolean;
+export declare function showPositionedByBlock<T>(field: Field<T>, block: BlockSvg, opt_onHide?: () => void, opt_secondaryYOffset?: number, manageEphemeralFocus?: boolean): boolean;
 /**
  * Shortcut to show and place the drop-down with positioning determined
  * by a particular field. The primary position will be below the field,
@@ -107,9 +112,14 @@ export declare function showPositionedByBlock<T>(field: Field<T>, block: BlockSv
  * @param field The field to position the dropdown against.
  * @param opt_onHide Optional callback for when the drop-down is hidden.
  * @param opt_secondaryYOffset Optional Y offset for above-block positioning.
+ * @param manageEphemeralFocus Whether ephemeral focus should be managed
+ *     according to the drop-down div's lifetime. Note that if a false value is
+ *     passed in here then callers should manage ephemeral focus directly
+ *     otherwise focus may not properly restore when the widget closes. Defaults
+ *     to true.
  * @returns True if the menu rendered below block; false if above.
  */
-export declare function showPositionedByField<T>(field: Field<T>, opt_onHide?: () => void, opt_secondaryYOffset?: number): boolean;
+export declare function showPositionedByField<T>(field: Field<T>, opt_onHide?: () => void, opt_secondaryYOffset?: number, manageEphemeralFocus?: boolean): boolean;
 /**
  * Show and place the drop-down.
  * The drop-down is placed with an absolute "origin point" (x, y) - i.e.,

package/core/field_image.d.ts

@@ -92,6 +92,12 @@ export declare class FieldImage extends Field<string> {
      * @param alt New alt text.
      */
     setAlt(alt: string | null): void;
+    /**
+     * Check whether this field should be clickable.
+     *
+     * @returns Whether this field is clickable.
+     */
+    isClickable(): boolean;
     /**
      * If field click is called, and click handler defined,
      * call the handler.

package/core/flyout_base.d.ts

@@ -401,9 +401,17 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
      *     is registered for that type.
      */
     protected getInflaterForType(type: string): IFlyoutInflater | null;
-    /** See IFocusableNode.getFocusableElement. */
+    /**
+     * See IFocusableNode.getFocusableElement.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     getFocusableElement(): HTMLElement | SVGElement;
-    /** See IFocusableNode.getFocusableTree. */
+    /**
+     * See IFocusableNode.getFocusableTree.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     getFocusableTree(): IFocusableTree;
     /** See IFocusableNode.onNodeFocus. */
     onNodeFocus(): void;
@@ -411,17 +419,37 @@ export declare abstract class Flyout extends DeleteArea implements IAutoHideable
     onNodeBlur(): void;
     /** See IFocusableNode.canBeFocused. */
     canBeFocused(): boolean;
-    /** See IFocusableTree.getRootFocusableNode. */
+    /**
+     * See IFocusableNode.getRootFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     getRootFocusableNode(): IFocusableNode;
-    /** See IFocusableTree.getRestoredFocusableNode. */
+    /**
+     * See IFocusableNode.getRestoredFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     getRestoredFocusableNode(_previousNode: IFocusableNode | null): IFocusableNode | null;
-    /** See IFocusableTree.getNestedTrees. */
+    /**
+     * See IFocusableNode.getNestedTrees.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     getNestedTrees(): Array<IFocusableTree>;
-    /** See IFocusableTree.lookUpFocusableNode. */
+    /**
+     * See IFocusableNode.lookUpFocusableNode.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
     lookUpFocusableNode(_id: string): IFocusableNode | null;
     /** See IFocusableTree.onTreeFocus. */
     onTreeFocus(_node: IFocusableNode, _previousTree: IFocusableTree | null): void;
-    /** See IFocusableTree.onTreeBlur. */
-    onTreeBlur(nextTree: IFocusableTree | null): void;
+    /**
+     * See IFocusableNode.onTreeBlur.
+     *
+     * @deprecated v12: Use the Flyout's workspace for focus operations, instead.
+     */
+    onTreeBlur(_nextTree: IFocusableTree | null): void;
 }
 //# sourceMappingURL=flyout_base.d.ts.map

package/core/focus_manager.d.ts

@@ -55,6 +55,7 @@ export declare class FocusManager {
     private currentlyHoldsEphemeralFocus;
     private lockFocusStateChanges;
     private recentlyLostAllFocus;
+    private isUpdatingFocusedNode;
     constructor(addGlobalEventListener: (type: string, listener: EventListener) => void);
     /**
      * Registers a new IFocusableTree for automatic focus management.
@@ -66,14 +67,30 @@ export declare class FocusManager {
      * This function throws if the provided tree is already currently registered
      * in this manager. Use isRegistered to check in cases when it can't be
      * certain whether the tree has been registered.
+     *
+     * The tree's registration can be customized to configure automatic tab stops.
+     * This specifically provides capability for the user to be able to tab
+     * navigate to the root of the tree but only when the tree doesn't hold active
+     * focus. If this functionality is disabled then the tree's root will
+     * automatically be made focusable (but not tabbable) when it is first focused
+     * in the same way as any other focusable node.
+     *
+     * @param tree The IFocusableTree to register.
+     * @param rootShouldBeAutoTabbable Whether the root of this tree should be
+     *     added as a top-level page tab stop when it doesn't hold active focus.
      */
-    registerTree(tree: IFocusableTree): void;
+    registerTree(tree: IFocusableTree, rootShouldBeAutoTabbable?: boolean): void;
     /**
      * Returns whether the specified tree has already been registered in this
      * manager using registerTree and hasn't yet been unregistered using
      * unregisterTree.
      */
     isRegistered(tree: IFocusableTree): boolean;
+    /**
+     * Returns the TreeRegistration for the specified tree, or null if the tree is
+     * not currently registered.
+     */
+    private lookUpRegistration;
     /**
      * Unregisters a IFocusableTree from automatic focus management.
      *
@@ -82,6 +99,9 @@ export declare class FocusManager {
      *
      * This function throws if the provided tree is not currently registered in
      * this manager.
+     *
+     * This function will reset the tree's root element tabindex if the tree was
+     * registered with automatic tab management.
      */
     unregisterTree(tree: IFocusableTree): void;
     /**
@@ -132,6 +152,9 @@ export declare class FocusManager {
      * canBeFocused() method returns false), it will be ignored and any existing
      * focus state will remain unchanged.
      *
+     * Note that this may update the specified node's element's tabindex to ensure
+     * that it can be properly read out by screenreaders while focused.
+     *
      * @param focusableNode The node that should receive active focus.
      */
     focusNode(focusableNode: IFocusableNode): void;

package/core/icons/icon.d.ts

@@ -72,5 +72,11 @@ export declare abstract class Icon implements IIcon {
     onNodeBlur(): void;
     /** See IFocusableNode.canBeFocused. */
     canBeFocused(): boolean;
+    /**
+     * Returns the block that this icon is attached to.
+     *
+     * @returns The block this icon is attached to.
+     */
+    getSourceBlock(): Block;
 }
 //# sourceMappingURL=icon.d.ts.map

package/core/interfaces/i_focusable_node.d.ts

@@ -17,13 +17,11 @@ export interface IFocusableNode {
      * - blocklyActiveFocus
      * - blocklyPassiveFocus
      *
-     * The returned element must also have a valid ID specified, and 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 also have a negative tabindex (since the focus
-     * manager itself will manage its tab index and a tab index must be present in
-     * order for the element to be focusable in the DOM).
+     * 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
@@ -32,7 +30,11 @@ export interface IFocusableNode {
      *
      * 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).
+     * 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.

package/core/keyboard_nav/block_navigation_policy.d.ts

@@ -4,8 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { BlockSvg } from '../block_svg.js';
+import type { Field } from '../field.js';
+import type { Icon } from '../icons/icon.js';
 import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
 import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+import { RenderedConnection } from '../rendered_connection.js';
 /**
  * Set of rules controlling keyboard navigation from a block.
  */
@@ -29,7 +32,7 @@ export declare class BlockNavigationPolicy implements INavigationPolicy<BlockSvg
      * 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
+     * @returns The first node of the next input/stack if the given block is a terminal
      *     block, or its next connection.
      */
     getNextSibling(current: BlockSvg): IFocusableNode | null;
@@ -56,4 +59,25 @@ export declare class BlockNavigationPolicy implements INavigationPolicy<BlockSvg
      */
     isApplicable(current: any): current is BlockSvg;
 }
+/**
+ * Returns the next/previous stack relative to the given block's stack.
+ *
+ * @param current The block whose stack will be navigated relative to.
+ * @param delta The difference in index to navigate; positive values navigate
+ *     to the nth next stack, while negative values navigate to the nth previous
+ *     stack.
+ * @returns The first block in the stack offset by `delta` relative to the
+ *     current block's stack, or the last block in the stack offset by `delta`
+ *     relative to the current block's stack when navigating backwards.
+ */
+export declare function navigateStacks(current: BlockSvg, delta: number): BlockSvg | null;
+/**
+ * Returns the next navigable item relative to the provided block child.
+ *
+ * @param current The navigable block child item to navigate relative to.
+ * @param delta The difference in index to navigate; positive values navigate
+ *     forward by n, while negative values navigate backwards by n.
+ * @returns The navigable block child offset by `delta` relative to `current`.
+ */
+export declare function navigateBlock(current: Icon | Field | RenderedConnection | BlockSvg, delta: number): IFocusableNode | null;
 //# sourceMappingURL=block_navigation_policy.d.ts.map

package/core/keyboard_nav/icon_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Icon } from '../icons/icon.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import type { INavigationPolicy } from '../interfaces/i_navigation_policy.js';
+/**
+ * Set of rules controlling keyboard navigation from an icon.
+ */
+export declare class IconNavigationPolicy implements INavigationPolicy<Icon> {
+    /**
+     * Returns the first child of the given icon.
+     *
+     * @param _current The icon to return the first child of.
+     * @returns Null.
+     */
+    getFirstChild(_current: Icon): IFocusableNode | null;
+    /**
+     * Returns the parent of the given icon.
+     *
+     * @param current The icon to return the parent of.
+     * @returns The source block of the given icon.
+     */
+    getParent(current: Icon): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given icon.
+     *
+     * @param current The icon to find the following element of.
+     * @returns The next icon, field or input following this icon, if any.
+     */
+    getNextSibling(current: Icon): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given icon.
+     *
+     * @param current The icon to find the preceding element of.
+     * @returns The icon's previous icon, if any.
+     */
+    getPreviousSibling(current: Icon): IFocusableNode | null;
+    /**
+     * Returns whether or not the given icon can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given icon can be focused.
+     */
+    isNavigable(current: Icon): boolean;
+    /**
+     * Returns whether the given object can be navigated from by this policy.
+     *
+     * @param current The object to check if this policy applies to.
+     * @returns True if the object is an Icon.
+     */
+    isApplicable(current: any): current is Icon;
+}
+//# sourceMappingURL=icon_navigation_policy.d.ts.map

package/core/keyboard_navigation_controller.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The KeyboardNavigationController handles coordinating Blockly-wide
+ * keyboard navigation behavior, such as enabling/disabling full
+ * cursor visualization.
+ */
+export declare class KeyboardNavigationController {
+    /** Whether the user is actively using keyboard navigation. */
+    private isActive;
+    /** Css class name added to body if keyboard nav is active. */
+    private activeClassName;
+    /**
+     * Sets whether a user is actively using keyboard navigation.
+     *
+     * If they are, apply a css class to the entire page so that
+     * focused items can apply additional styling for keyboard users.
+     *
+     * Note that since enabling keyboard navigation presents significant UX changes
+     * (such as cursor visualization and move mode), callers should take care to
+     * only set active keyboard navigation when they have a high confidence in that
+     * being the correct state. In general, in any given mouse or key input situation
+     * callers can choose one of three paths:
+     * 1. Do nothing. This should be the choice for neutral actions that don't
+     *    predominantly imply keyboard or mouse usage (such as clicking to select a block).
+     * 2. Disable keyboard navigation. This is the best choice when a user is definitely
+     *    predominantly using the mouse (such as using a right click to open the context menu).
+     * 3. Enable keyboard navigation. This is the best choice when there's high confidence
+     *    a user actually intends to use it (such as attempting to use the arrow keys to move
+     *    around).
+     *
+     * @param isUsing
+     */
+    setIsActive(isUsing?: boolean): void;
+    /**
+     * @returns true if the user is actively using keyboard navigation
+     * (e.g., has recently taken some action that is only relevant to keyboard users)
+     */
+    getIsActive(): boolean;
+    /** Adds or removes the css class that indicates keyboard navigation is active. */
+    private updateActiveVisualization;
+}
+/** Singleton instance of the keyboard navigation controller. */
+export declare const keyboardNavigationController: KeyboardNavigationController;
+//# sourceMappingURL=keyboard_navigation_controller.d.ts.map

package/core/toolbox/toolbox.d.ts

@@ -6,7 +6,7 @@
 import * as browserEvents from '../browser_events.js';
 import { DeleteArea } from '../delete_area.js';
 import '../events/events_toolbox_item_select.js';
-import type { IAutoHideable } from '../interfaces/i_autohideable.js';
+import { type IAutoHideable } from '../interfaces/i_autohideable.js';
 import type { IDraggable } from '../interfaces/i_draggable.js';
 import type { IFlyout } from '../interfaces/i_flyout.js';
 import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
@@ -412,6 +412,6 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
     /** See IFocusableTree.onTreeFocus. */
     onTreeFocus(node: IFocusableNode, _previousTree: IFocusableTree | null): void;
     /** See IFocusableTree.onTreeBlur. */
-    onTreeBlur(_nextTree: IFocusableTree | null): void;
+    onTreeBlur(nextTree: IFocusableTree | null): void;
 }
 //# sourceMappingURL=toolbox.d.ts.map

package/index.mjs

@@ -55,6 +55,7 @@ export const {
   INPUT_VALUE,
   Input,
   InsertionMarkerPreviewer,
+  KeyboardNavigationController,
   LabelFlyoutInflater,
   LineCursor,
   Marker,
@@ -144,7 +145,10 @@ export const {
   isSelectable,
   isSerializable,
   isVariableBackedParameterModel,
+  keyboardNavigationController,
   layers,
+  navigateBlock,
+  navigateStacks,
   procedures,
   registry,
   renderManagement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockly",
-  "version": "12.0.0",
+  "version": "12.1.0-beta.0",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"
@@ -68,7 +68,7 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@blockly/block-test": "^6.0.4",
-    "@blockly/dev-tools": "^8.0.6",
+    "@blockly/dev-tools": "^9.0.0",
     "@blockly/theme-modern": "^6.0.3",
     "@hyperjump/browser": "^1.1.4",
     "@hyperjump/json-schema": "^1.5.0",
@@ -99,7 +99,7 @@
     "http-server": "^14.0.0",
     "json5": "^2.2.0",
     "markdown-tables-to-json": "^0.1.7",
-    "mocha": "^10.0.0",
+    "mocha": "^11.3.0",
     "patch-package": "^8.0.0",
     "prettier": "^3.3.3",
     "prettier-plugin-organize-imports": "^4.0.0",