blockly 12.0.0-beta.2 → 12.0.0-beta.4

package/core/block_svg.d.ts

@@ -10,18 +10,18 @@
  */
 import './events/events_selected.js';
 import { Block } from './block.js';
-import { IDeletable } from './blockly.js';
 import { BlockCopyData } from './clipboard/block_paster.js';
 import type { Connection } from './connection.js';
 import { ConnectionType } from './connection_type.js';
 import { ContextMenuOption, LegacyContextMenuOption } from './contextmenu_registry.js';
-import type { Field } from './field.js';
 import { IconType } from './icons/icon_types.js';
 import { MutatorIcon } from './icons/mutator_icon.js';
 import type { Input } from './inputs/input.js';
 import type { IASTNodeLocationSvg } from './interfaces/i_ast_node_location_svg.js';
 import type { IBoundedElement } from './interfaces/i_bounded_element.js';
+import { IContextMenu } from './interfaces/i_contextmenu.js';
 import type { ICopyable } from './interfaces/i_copyable.js';
+import { IDeletable } from './interfaces/i_deletable.js';
 import type { IDragStrategy, IDraggable } from './interfaces/i_draggable.js';
 import { IIcon } from './interfaces/i_icon.js';
 import { RenderedConnection } from './rendered_connection.js';
@@ -36,7 +36,7 @@ import type { WorkspaceSvg } from './workspace_svg.js';
  * Class for a block's SVG representation.
  * Not normally called directly, workspace.newBlock() is preferred.
  */
-export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBoundedElement, ICopyable<BlockCopyData>, IDraggable, IDeletable {
+export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBoundedElement, IContextMenu, ICopyable<BlockCopyData>, IDraggable, IDeletable {
     /**
      * Constant for identifying rows that are to be rendered inline.
      * Don't collide with Blockly.inputTypes.
@@ -232,13 +232,6 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * for that state.
      */
     private updateCollapsed;
-    /**
-     * Open the next (or previous) FieldTextInput.
-     *
-     * @param start Current field.
-     * @param forward If true go forward, otherwise backward.
-     */
-    tab(start: Field, forward: boolean): void;
     /**
      * Handle a pointerdown on an SVG block.
      *
@@ -256,14 +249,20 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      *
      * @returns Context menu options or null if no menu.
      */
-    protected generateContextMenu(): Array<ContextMenuOption | LegacyContextMenuOption> | null;
+    protected generateContextMenu(e: Event): Array<ContextMenuOption | LegacyContextMenuOption> | null;
+    /**
+     * Gets the location in which to show the context menu for this block.
+     * Use the location of a click if the block was clicked, or a location
+     * based on the block's fields otherwise.
+     */
+    protected calculateContextMenuLocation(e: Event): Coordinate;
     /**
      * Show the context menu for this block.
      *
      * @param e Mouse event.
      * @internal
      */
-    showContextMenu(e: PointerEvent): void;
+    showContextMenu(e: Event): void;
     /**
      * Updates the locations of any parts of the block that need to know where
      * they are (e.g. connections, icons).
@@ -713,6 +712,13 @@ export declare class BlockSvg extends Block implements IASTNodeLocationSvg, IBou
      * @internal
      */
     highlightShapeForInput(conn: RenderedConnection, add: boolean): void;
+    /**
+     * Returns the drag strategy currently in use by this block.
+     *
+     * @internal
+     * @returns This block's drag strategy.
+     */
+    getDragStrategy(): IDragStrategy;
     /** Sets the drag strategy for this block. */
     setDragStrategy(dragStrategy: IDragStrategy): void;
     /** Returns whether this block is movable or not. */

package/core/blockly.d.ts

@@ -55,6 +55,7 @@ import { FlyoutItem } from './flyout_item.js';
 import { FlyoutMetricsManager } from './flyout_metrics_manager.js';
 import { FlyoutSeparator } from './flyout_separator.js';
 import { VerticalFlyout } from './flyout_vertical.js';
+import { FocusManager, ReturnEphemeralFocus, getFocusManager } from './focus_manager.js';
 import { CodeGenerator } from './generator.js';
 import { Gesture } from './gesture.js';
 import { Grid } from './grid.js';
@@ -106,10 +107,8 @@ import { IVariableBackedParameterModel, isVariableBackedParameterModel } from '.
 import { IVariableMap } from './interfaces/i_variable_map.js';
 import { IVariableModel, IVariableState } from './interfaces/i_variable_model.js';
 import { ASTNode } from './keyboard_nav/ast_node.js';
-import { BasicCursor } from './keyboard_nav/basic_cursor.js';
-import { Cursor } from './keyboard_nav/cursor.js';
+import { CursorOptions, LineCursor } from './keyboard_nav/line_cursor.js';
 import { Marker } from './keyboard_nav/marker.js';
-import { TabNavigateCursor } from './keyboard_nav/tab_navigate_cursor.js';
 import type { LayerManager } from './layer_manager.js';
 import * as layers from './layers.js';
 import { MarkerManager } from './marker_manager.js';
@@ -272,7 +271,7 @@ export declare const VARIABLE_DYNAMIC_CATEGORY_NAME: string;
  * procedure blocks.
  */
 export declare const PROCEDURE_CATEGORY_NAME: string;
-export { ASTNode, BasicCursor, Block, BlockSvg, BlocklyOptions, Blocks, CollapsibleToolboxCategory, ComponentManager, Connection, ConnectionChecker, ConnectionDB, ConnectionType, ContextMenu, ContextMenuItems, ContextMenuRegistry, Css, Cursor, DeleteArea, DragTarget, Events, Extensions, 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 { ASTNode, Block, BlockSvg, BlocklyOptions, Blocks, CollapsibleToolboxCategory, ComponentManager, Connection, ConnectionChecker, ConnectionDB, ConnectionType, ContextMenu, ContextMenuItems, ContextMenuRegistry, Css, CursorOptions, 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, CodeGenerator as Generator, Gesture, Grid, HorizontalFlyout, IASTNodeLocation, IASTNodeLocationSvg, IASTNodeLocationWithBlock, 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, Scrollbar, ScrollbarPair, SeparatorFlyoutInflater, ShortcutRegistry, TabNavigateCursor, Theme, ThemeManager, Toolbox, ToolboxCategory, ToolboxItem, ToolboxSeparator, Trashcan, UnattachedFieldError, VariableMap, VariableModel, VerticalFlyout, Workspace, WorkspaceAudio, WorkspaceDragger, WorkspaceSvg, ZoomControls, config, 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, CodeGenerator as Generator, Gesture, Grid, HorizontalFlyout, IASTNodeLocation, IASTNodeLocationSvg, IASTNodeLocationWithBlock, 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, };
 //# sourceMappingURL=blockly.d.ts.map

package/core/comments/rendered_workspace_comment.d.ts

@@ -95,7 +95,7 @@ export declare class RenderedWorkspaceComment extends WorkspaceComment implement
      */
     toCopyData(): WorkspaceCommentCopyData | null;
     /** Show a context menu for this comment. */
-    showContextMenu(e: PointerEvent): void;
+    showContextMenu(e: Event): void;
     /** Snap this comment to the nearest grid point. */
     snapToGrid(): void;
 }

package/core/contextmenu.d.ts

@@ -7,9 +7,12 @@ import type { Block } from './block.js';
 import type { BlockSvg } from './block_svg.js';
 import type { ContextMenuOption, LegacyContextMenuOption } from './contextmenu_registry.js';
 import * as serializationBlocks from './serialization/blocks.js';
+import { Coordinate } from './utils/coordinate.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Gets the block the context menu is currently attached to.
+ * It is not recommended that you use this function; instead,
+ * use the scope object passed to the context menu callback.
  *
  * @returns The block the context menu is attached to.
  */
@@ -23,12 +26,13 @@ export declare function setCurrentBlock(block: Block | null): void;
 /**
  * Construct the menu based on the list of options and show the menu.
  *
- * @param e Mouse event.
+ * @param menuOpenEvent Event that caused the menu to open.
  * @param options Array of menu options.
  * @param rtl True if RTL, false if LTR.
  * @param workspace The workspace associated with the context menu, if any.
+ * @param location The screen coordinates at which to show the menu.
  */
-export declare function show(e: PointerEvent, options: (ContextMenuOption | LegacyContextMenuOption)[], rtl: boolean, workspace?: WorkspaceSvg): void;
+export declare function show(menuOpenEvent: Event, options: (ContextMenuOption | LegacyContextMenuOption)[], rtl: boolean, workspace?: WorkspaceSvg, location?: Coordinate): void;
 /**
  * Hide the context menu.
  */

package/core/contextmenu_registry.d.ts

@@ -10,6 +10,7 @@
  */
 import type { BlockSvg } from './block_svg.js';
 import { RenderedWorkspaceComment } from './comments/rendered_workspace_comment.js';
+import { Coordinate } from './utils/coordinate.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class for the registry of context menu items. This is intended to be a
@@ -54,7 +55,7 @@ export declare class ContextMenuRegistry {
      *     block being clicked on)
      * @returns the list of ContextMenuOptions
      */
-    getContextMenuOptions(scopeType: ScopeType, scope: Scope): ContextMenuOption[];
+    getContextMenuOptions(scopeType: ScopeType, scope: Scope, menuOpenEvent: Event): ContextMenuOption[];
 }
 export declare namespace ContextMenuRegistry {
     /**
@@ -91,12 +92,13 @@ export declare namespace ContextMenuRegistry {
         /**
          * @param scope Object that provides a reference to the thing that had its
          *     context menu opened.
-         * @param e The original event that triggered the context menu to open. Not
-         *     the event that triggered the click on the option.
+         * @param menuOpenEvent The original event that triggered the context menu to open.
+         * @param menuSelectEvent The event that triggered the option being selected.
+         * @param location The location in screen coordinates where the menu was opened.
          */
-        callback: (scope: Scope, e: PointerEvent) => void;
+        callback: (scope: Scope, menuOpenEvent: Event, menuSelectEvent: Event, location: Coordinate) => void;
         displayText: ((p1: Scope) => string | HTMLElement) | string | HTMLElement;
-        preconditionFn: (p1: Scope) => string;
+        preconditionFn: (p1: Scope, menuOpenEvent: Event) => string;
         separator?: never;
     }
     /**
@@ -128,10 +130,11 @@ export declare namespace ContextMenuRegistry {
         /**
          * @param scope Object that provides a reference to the thing that had its
          *     context menu opened.
-         * @param e The original event that triggered the context menu to open. Not
-         *     the event that triggered the click on the option.
+         * @param menuOpenEvent The original event that triggered the context menu to open.
+         * @param menuSelectEvent The event that triggered the option being selected.
+         * @param location The location in screen coordinates where the menu was opened.
          */
-        callback: (scope: Scope, e: PointerEvent) => void;
+        callback: (scope: Scope, menuOpenEvent: Event, menuSelectEvent: Event, location: Coordinate) => void;
         separator?: never;
     }
     /**

package/core/dragging/block_drag_strategy.d.ts

@@ -35,6 +35,14 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * from any parent blocks.
      */
     startDrag(e?: PointerEvent): void;
+    /**
+     * Get whether the drag should act on a single block or a block stack.
+     *
+     * @param e The instigating pointer event, if any.
+     * @returns True if just the initial block should be dragged out, false
+     *     if all following blocks should also be dragged.
+     */
+    protected shouldHealStack(e: PointerEvent | undefined): boolean;
     /** Starts a drag on a shadow, recording the drag offset. */
     private startDraggingShadow;
     /**
@@ -84,6 +92,10 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * compatible type (input, output, etc) and connection check.
      */
     private getConnectionCandidate;
+    /**
+     * Get the radius to use when searching for a nearby valid connection.
+     */
+    protected getSearchRadius(): number;
     /**
      * Returns all of the connections we might connect to blocks on the workspace.
      *

package/core/field.d.ts

@@ -203,8 +203,10 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * intend because the behavior was kind of hacked in. If you are thinking
      * about overriding this function, post on the forum with your intended
      * behavior to see if there's another approach.
+     *
+     * @internal
      */
-    protected isFullBlockField(): boolean;
+    isFullBlockField(): boolean;
     /**
      * Create a field border rect element. Not to be overridden by subclasses.
      * Instead modify the result of the function inside initView, or create a
@@ -660,12 +662,6 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * @returns True if we should flip in RTL.
      */
     getFlipRtl(): boolean;
-    /**
-     * Returns whether or not the field is tab navigable.
-     *
-     * @returns True if the field is tab navigable.
-     */
-    isTabNavigable(): boolean;
     /**
      * Handles the given keyboard shortcut.
      *

package/core/field_input.d.ts

@@ -79,7 +79,7 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
     constructor(value?: string | typeof Field.SKIP_SETUP, validator?: FieldInputValidator<T> | null, config?: FieldInputConfig);
     protected configure_(config: FieldInputConfig): void;
     initView(): void;
-    protected isFullBlockField(): boolean;
+    isFullBlockField(): boolean;
     /**
      * Called by setValue if the text input is not valid. If the field is
      * currently being edited it reverts value of the field to the previous
@@ -214,12 +214,6 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
      *     div.
      */
     repositionForWindowResize(): boolean;
-    /**
-     * Returns whether or not the field is tab navigable.
-     *
-     * @returns True if the field is tab navigable.
-     */
-    isTabNavigable(): boolean;
     /**
      * Use the `getText_` developer hook to override the field's text
      * representation. When we're currently editing, return the current HTML value

package/core/field_variable.d.ts

@@ -47,7 +47,8 @@ export declare class FieldVariable extends FieldDropdown {
      *     field's value. Takes in a variable ID  & returns a validated variable
      *     ID, or null to abort the change.
      * @param variableTypes A list of the types of variables to include in the
-     *     dropdown. Will only be used if config is not provided.
+     *     dropdown. Pass `null` to include all types that exist on the
+     *     workspace. Will only be used if config is not provided.
      * @param defaultType The type of variable to create if this field's value
      *     is not explicitly set.  Defaults to ''. Will only be used if config
      *     is not provided.
@@ -56,7 +57,7 @@ export declare class FieldVariable extends FieldDropdown {
      * https://developers.google.com/blockly/guides/create-custom-blocks/fields/built-in-fields/variable#creation}
      * for a list of properties this parameter supports.
      */
-    constructor(varName: string | null | typeof Field.SKIP_SETUP, validator?: FieldVariableValidator, variableTypes?: string[], defaultType?: string, config?: FieldVariableConfig);
+    constructor(varName: string | null | typeof Field.SKIP_SETUP, validator?: FieldVariableValidator, variableTypes?: string[] | null, defaultType?: string, config?: FieldVariableConfig);
     /**
      * Configure the field based on the given map of options.
      *
@@ -173,7 +174,6 @@ export declare class FieldVariable extends FieldDropdown {
      * Return a list of variable types to include in the dropdown.
      *
      * @returns Array of variable types.
-     * @throws {Error} if variableTypes is an empty array.
      */
     private getVariableTypes;
     /**

package/core/focus_manager.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from './interfaces/i_focusable_node.js';
+import type { IFocusableTree } from './interfaces/i_focusable_tree.js';
+/**
+ * Type declaration for returning focus to FocusManager upon completing an
+ * ephemeral UI flow (such as a dialog).
+ *
+ * See FocusManager.takeEphemeralFocus for more details.
+ */
+export type ReturnEphemeralFocus = () => void;
+/**
+ * A per-page singleton that manages Blockly focus across one or more
+ * IFocusableTrees, and bidirectionally synchronizes this focus with the DOM.
+ *
+ * Callers that wish to explicitly change input focus for select Blockly
+ * components on the page should use the focus functions in this manager.
+ *
+ * The manager is responsible for handling focus events from the DOM (which may
+ * may arise from users clicking on page elements) and ensuring that
+ * corresponding IFocusableNodes are clearly marked as actively/passively
+ * highlighted in the same way that this would be represented with calls to
+ * focusNode().
+ */
+export declare class FocusManager {
+    /**
+     * The CSS class assigned to IFocusableNode elements that presently have
+     * active DOM and Blockly focus.
+     *
+     * This should never be used directly. Instead, rely on FocusManager to ensure
+     * nodes have active focus (either automatically through DOM focus or manually
+     * through the various focus* methods provided by this class).
+     *
+     * It's recommended to not query using this class name, either. Instead, use
+     * FocusableTreeTraverser or IFocusableTree's methods to find a specific node.
+     */
+    static readonly ACTIVE_FOCUS_NODE_CSS_CLASS_NAME = "blocklyActiveFocus";
+    /**
+     * The CSS class assigned to IFocusableNode elements that presently have
+     * passive focus (that is, they were the most recent node in their relative
+     * tree to have active focus--see ACTIVE_FOCUS_NODE_CSS_CLASS_NAME--and will
+     * receive active focus again if their surrounding tree is requested to become
+     * focused, i.e. using focusTree below).
+     *
+     * See ACTIVE_FOCUS_NODE_CSS_CLASS_NAME for caveats and limitations around
+     * 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 currentlyHoldsEphemeralFocus;
+    constructor(addGlobalEventListener: (type: string, listener: EventListener) => void);
+    /**
+     * Registers a new IFocusableTree for automatic focus management.
+     *
+     * If the tree currently has an element with DOM focus, it will not affect the
+     * internal state in this manager until the focus changes to a new,
+     * now-monitored element/node.
+     *
+     * 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.
+     */
+    registerTree(tree: IFocusableTree): 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;
+    /**
+     * Unregisters a IFocusableTree from automatic focus management.
+     *
+     * If the tree had a previous focused node, it will have its highlight
+     * removed. This function does NOT change DOM focus.
+     *
+     * This function throws if the provided tree is not currently registered in
+     * this manager.
+     */
+    unregisterTree(tree: IFocusableTree): void;
+    /**
+     * Returns the current IFocusableTree that has focus, or null if none
+     * currently do.
+     *
+     * Note also that if ephemeral focus is currently captured (e.g. using
+     * takeEphemeralFocus) then the returned tree here may not currently have DOM
+     * focus.
+     */
+    getFocusedTree(): IFocusableTree | null;
+    /**
+     * Returns the current IFocusableNode with focus (which is always tied to a
+     * focused IFocusableTree), or null if there isn't one.
+     *
+     * Note that this function will maintain parity with
+     * IFocusableTree.getFocusedNode(). That is, if a tree itself has focus but
+     * none of its non-root children do, this will return null but
+     * getFocusedTree() will not.
+     *
+     * Note also that if ephemeral focus is currently captured (e.g. using
+     * takeEphemeralFocus) then the returned node here may not currently have DOM
+     * focus.
+     */
+    getFocusedNode(): IFocusableNode | null;
+    /**
+     * Focuses the specific IFocusableTree. This either means restoring active
+     * focus to the tree's passively focused node, or focusing the tree's root
+     * node.
+     *
+     * Note that if the specified tree already has a focused node then this will
+     * not change any existing focus (unless that node has passive focus, then it
+     * will be restored to active focus).
+     *
+     * See getFocusedNode for details on how other nodes are affected.
+     *
+     * @param focusableTree The tree that should receive active
+     *     focus.
+     */
+    focusTree(focusableTree: IFocusableTree): void;
+    /**
+     * Focuses DOM input on the selected 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.
+     */
+    focusNode(focusableNode: IFocusableNode): void;
+    /**
+     * Ephemerally captures focus for a selected element until the returned lambda
+     * is called. This is expected to be especially useful for ephemeral UI flows
+     * like dialogs.
+     *
+     * IMPORTANT: the returned lambda *must* be called, otherwise automatic focus
+     * will no longer work anywhere on the page. It is highly recommended to tie
+     * the lambda call to the closure of the corresponding UI so that if input is
+     * manually changed to an element outside of the ephemeral UI, the UI should
+     * close and automatic input restored. Note that this lambda must be called
+     * exactly once and that subsequent calls will throw an error.
+     *
+     * Note that the manager will continue to track DOM input signals even when
+     * ephemeral focus is active, but it won't actually change node state until
+     * the returned lambda is called. Additionally, only 1 ephemeral focus context
+     * can be active at any given time (attempting to activate more than one
+     * simultaneously will result in an error being thrown).
+     */
+    takeEphemeralFocus(focusableElement: HTMLElement | SVGElement): ReturnEphemeralFocus;
+    private defocusCurrentFocusedNode;
+    private setNodeToActive;
+    private setNodeToPassive;
+    private removeHighlight;
+}
+/**
+ * Returns the page-global FocusManager.
+ *
+ * The returned instance is guaranteed to not change across function calls, but
+ * may change across page loads.
+ */
+export declare function getFocusManager(): FocusManager;
+//# sourceMappingURL=focus_manager.d.ts.map

package/core/interfaces/i_focusable_node.d.ts

@@ -18,7 +18,10 @@ export interface IFocusableNode {
      * - blocklyPassiveFocus
      *
      * The returned element must also have a valid ID specified, and unique to the
-     * element relative to its nearest IFocusableTree parent.
+     * element relative to its nearest IFocusableTree parent. It 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).
      *
      * It's expected the return element will not change for the lifetime of the
      * node.

package/core/interfaces/i_focusable_tree.d.ts

@@ -18,16 +18,14 @@ import type { IFocusableNode } from './i_focusable_node.js';
  * page at any given time). The idea of passive focus is to provide context to
  * users on where their focus will be restored upon navigating back to a
  * previously focused tree.
+ *
+ * Note that if the tree's current focused node (passive or active) is needed,
+ * FocusableTreeTraverser.findFocusedNode can be used.
+ *
+ * Note that if specific nodes are needed to be retrieved for this tree, either
+ * use lookUpFocusableNode or FocusableTreeTraverser.findFocusableNodeFor.
  */
 export interface IFocusableTree {
-    /**
-     * Returns the current node with focus in this tree, or null if none (or if
-     * the root has focus).
-     *
-     * Note that this will never return a node from a nested sub-tree as that tree
-     * should specifically be called in order to retrieve its focused node.
-     */
-    getFocusedNode(): IFocusableNode | null;
     /**
      * Returns the top-level focusable node of the tree.
      *
@@ -37,12 +35,24 @@ export interface IFocusableTree {
      */
     getRootFocusableNode(): IFocusableNode;
     /**
-     * Returns the IFocusableNode corresponding to the select element, or null if
-     * the element does not have such a node.
+     * Returns all directly nested trees under this tree.
+     *
+     * Note that the returned list of trees doesn't need to be stable, however all
+     * returned trees *do* need to be registered with FocusManager. Additionally,
+     * this must return actual nested trees as omitting a nested tree will affect
+     * how focus changes map to a specific node and its tree, potentially leading
+     * to user confusion.
+     */
+    getNestedTrees(): Array<IFocusableTree>;
+    /**
+     * Returns the IFocusableNode corresponding to the specified element ID, or
+     * null if there's no exact node within this tree with that ID or if the ID
+     * corresponds to the root of the tree.
+     *
+     * This will never match against nested trees.
      *
-     * The provided element must have a non-null ID that conforms to the contract
-     * mentioned in IFocusableNode.
+     * @param id The ID of the node's focusable HTMLElement or SVGElement.
      */
-    findFocusableNodeFor(element: HTMLElement | SVGElement): IFocusableNode | null;
+    lookUpFocusableNode(id: string): IFocusableNode | null;
 }
 //# sourceMappingURL=i_focusable_tree.d.ts.map

package/core/keyboard_nav/ast_node.d.ts

@@ -72,7 +72,7 @@ export declare class ASTNode {
      * @returns The workspace coordinate or null if the location is not a
      *     workspace.
      */
-    getWsCoordinate(): Coordinate;
+    getWsCoordinate(): Coordinate | null;
     /**
      * Whether the node points to a connection.
      *
@@ -213,7 +213,7 @@ export declare class ASTNode {
      * @param field The location of the AST node.
      * @returns An AST node pointing to a field.
      */
-    static createFieldNode(field: Field): ASTNode | null;
+    static createFieldNode(field: Field): ASTNode;
     /**
      * Creates an AST node pointing to a connection. If the connection has a
      * parent input then create an AST node of type input that will hold the
@@ -237,7 +237,7 @@ export declare class ASTNode {
      * @param block The block used to create an AST node.
      * @returns An AST node pointing to a block.
      */
-    static createBlockNode(block: Block): ASTNode | null;
+    static createBlockNode(block: Block): ASTNode;
     /**
      * Create an AST node of type stack. A stack, represented by its top block, is
      *     the set of all blocks connected to a top block, including the top
@@ -248,7 +248,7 @@ export declare class ASTNode {
      * @returns An AST node of type stack that points to the top block on the
      *     stack.
      */
-    static createStackNode(topBlock: Block): ASTNode | null;
+    static createStackNode(topBlock: Block): ASTNode;
     /**
      * Create an AST node of type button. A button in this case refers
      * specifically to a button in a flyout.
@@ -258,7 +258,7 @@ export declare class ASTNode {
      * @returns An AST node of type stack that points to the top block on the
      *     stack.
      */
-    static createButtonNode(button: FlyoutButton): ASTNode | null;
+    static createButtonNode(button: FlyoutButton): ASTNode;
     /**
      * Creates an AST node pointing to a workspace.
      *
@@ -267,7 +267,7 @@ export declare class ASTNode {
      * @returns An AST node pointing to a workspace and a position on the
      *     workspace.
      */
-    static createWorkspaceNode(workspace: Workspace | null, wsCoordinate: Coordinate | null): ASTNode | null;
+    static createWorkspaceNode(workspace: Workspace, wsCoordinate: Coordinate): ASTNode;
     /**
      * Creates an AST node for the top position on a block.
      * This is either an output connection, previous connection, or block.