blockly 12.0.0-beta.1 → 12.0.0-beta.3

package/core/block_flyout_inflater.d.ts

@@ -16,7 +16,6 @@ import type { WorkspaceSvg } from './workspace_svg.js';
 export declare class BlockFlyoutInflater implements IFlyoutInflater {
     protected permanentlyDisabledBlocks: Set<BlockSvg>;
     protected listeners: Map<string, browserEvents.Data[]>;
-    protected flyoutWorkspace?: WorkspaceSvg;
     protected flyout?: IFlyout;
     private capacityWrapper;
     /**
@@ -27,10 +26,10 @@ export declare class BlockFlyoutInflater implements IFlyoutInflater {
      * Inflates a flyout block from the given state and adds it to the flyout.
      *
      * @param state A JSON representation of a flyout block.
-     * @param flyoutWorkspace The workspace to create the block on.
+     * @param flyout The flyout to create the block on.
      * @returns A newly created block.
      */
-    load(state: object, flyoutWorkspace: WorkspaceSvg): FlyoutItem;
+    load(state: object, flyout: IFlyout): FlyoutItem;
     /**
      * Creates a block on the given workspace.
      *
@@ -60,11 +59,11 @@ export declare class BlockFlyoutInflater implements IFlyoutInflater {
      */
     protected removeListeners(blockId: string): void;
     /**
-     * Updates this inflater's flyout workspace.
+     * Updates this inflater's flyout.
      *
-     * @param workspace The workspace of the flyout that owns this inflater.
+     * @param flyout The flyout that owns this inflater.
      */
-    protected setFlyoutWorkspace(workspace: WorkspaceSvg): void;
+    protected setFlyout(flyout: IFlyout): void;
     /**
      * Updates the enabled state of the given block based on the capacity of the
      * workspace.

package/core/block_svg.d.ts

@@ -15,7 +15,6 @@ 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';
@@ -232,13 +231,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.
      *

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';
@@ -84,6 +85,8 @@ import { IDragTarget } from './interfaces/i_drag_target.js';
 import { IDragStrategy, IDraggable, isDraggable } from './interfaces/i_draggable.js';
 import { IDragger } from './interfaces/i_dragger.js';
 import { IFlyout } from './interfaces/i_flyout.js';
+import { IFocusableNode } from './interfaces/i_focusable_node.js';
+import { IFocusableTree } from './interfaces/i_focusable_tree.js';
 import { IHasBubble, hasBubble } from './interfaces/i_has_bubble.js';
 import { IIcon, isIcon } from './interfaces/i_icon.js';
 import { IKeyboardAccessible } from './interfaces/i_keyboard_accessible.js';
@@ -104,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';
@@ -270,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, 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/bubbles/text_bubble.d.ts

@@ -26,12 +26,12 @@ export declare class TextBubble extends Bubble {
      * broken up by newlines.
      */
     private stringToSvg;
-    /** Creates the paragraph container for this bubble's view's spans. */
+    /** Creates the paragraph container for this bubble's view's text fragments. */
     private createParagraph;
-    /** Creates the spans visualizing the text of this bubble. */
-    private createSpans;
-    /** Right aligns the given spans. */
-    private rightAlignSpans;
+    /** Creates the text fragments visualizing the text of this bubble. */
+    private createTextFragments;
+    /** Right aligns the given text fragments. */
+    private rightAlignTextFragments;
     /** Updates the size of this bubble to account for the size of the text. */
     private updateBubbleSize;
 }

package/core/button_flyout_inflater.d.ts

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { FlyoutItem } from './flyout_item.js';
+import type { IFlyout } from './interfaces/i_flyout.js';
 import type { IFlyoutInflater } from './interfaces/i_flyout_inflater.js';
-import type { WorkspaceSvg } from './workspace_svg.js';
 /**
  * Class responsible for creating buttons for flyouts.
  */
@@ -14,10 +14,10 @@ export declare class ButtonFlyoutInflater implements IFlyoutInflater {
      * Inflates a flyout button from the given state and adds it to the flyout.
      *
      * @param state A JSON representation of a flyout button.
-     * @param flyoutWorkspace The workspace to create the button on.
+     * @param flyout The flyout to create the button on.
      * @returns A newly created FlyoutButton.
      */
-    load(state: object, flyoutWorkspace: WorkspaceSvg): FlyoutItem;
+    load(state: object, flyout: IFlyout): FlyoutItem;
     /**
      * Returns the amount of space that should follow this button.
      *

package/core/comments/comment_view.d.ts

@@ -8,7 +8,7 @@ import { Coordinate } from '../utils/coordinate.js';
 import { Size } from '../utils/size.js';
 import { WorkspaceSvg } from '../workspace_svg.js';
 export declare class CommentView implements IRenderedElement {
-    private readonly workspace;
+    readonly workspace: WorkspaceSvg;
     /** The root group element of the comment view. */
     private svgRoot;
     /**
@@ -62,9 +62,9 @@ export declare class CommentView implements IRenderedElement {
      */
     private resizePointerMoveListener;
     /** Whether this comment view is currently being disposed or not. */
-    private disposing;
+    protected disposing: boolean;
     /** Whether this comment view has been disposed or not. */
-    private disposed;
+    protected disposed: boolean;
     /** Size of this comment when the resize drag was initiated. */
     private preResizeSize?;
     /** The default size of newly created comments. */

package/core/contextmenu_registry.d.ts

@@ -62,7 +62,7 @@ export declare namespace ContextMenuRegistry {
      * rendered in multiple scopes, e.g. on both a block and a workspace, it
      * should be registered for each scope.
      */
-    enum ScopeType {
+    export enum ScopeType {
         BLOCK = "block",
         WORKSPACE = "workspace",
         COMMENT = "comment"
@@ -71,15 +71,23 @@ export declare namespace ContextMenuRegistry {
      * The actual workspace/block where the menu is being rendered. This is passed
      * to callback and displayText functions that depend on this information.
      */
-    interface Scope {
+    export interface Scope {
         block?: BlockSvg;
         workspace?: WorkspaceSvg;
         comment?: RenderedWorkspaceComment;
     }
     /**
-     * A menu item as entered in the registry.
+     * Fields common to all context menu registry items.
+     */
+    interface CoreRegistryItem {
+        scopeType: ScopeType;
+        weight: number;
+        id: string;
+    }
+    /**
+     * A representation of a normal, clickable menu item in the registry.
      */
-    interface RegistryItem {
+    interface ActionRegistryItem extends CoreRegistryItem {
         /**
          * @param scope Object that provides a reference to the thing that had its
          *     context menu opened.
@@ -87,16 +95,34 @@ export declare namespace ContextMenuRegistry {
          *     the event that triggered the click on the option.
          */
         callback: (scope: Scope, e: PointerEvent) => void;
-        scopeType: ScopeType;
         displayText: ((p1: Scope) => string | HTMLElement) | string | HTMLElement;
         preconditionFn: (p1: Scope) => string;
+        separator?: never;
+    }
+    /**
+     * A representation of a menu separator item in the registry.
+     */
+    interface SeparatorRegistryItem extends CoreRegistryItem {
+        separator: true;
+        callback?: never;
+        displayText?: never;
+        preconditionFn?: never;
+    }
+    /**
+     * A menu item as entered in the registry.
+     */
+    export type RegistryItem = ActionRegistryItem | SeparatorRegistryItem;
+    /**
+     * Fields common to all context menu items as used by contextmenu.ts.
+     */
+    export interface CoreContextMenuOption {
+        scope: Scope;
         weight: number;
-        id: string;
     }
     /**
-     * A menu item as presented to contextmenu.js.
+     * A representation of a normal, clickable menu item in contextmenu.ts.
      */
-    interface ContextMenuOption {
+    export interface ActionContextMenuOption extends CoreContextMenuOption {
         text: string | HTMLElement;
         enabled: boolean;
         /**
@@ -106,18 +132,32 @@ export declare namespace ContextMenuRegistry {
          *     the event that triggered the click on the option.
          */
         callback: (scope: Scope, e: PointerEvent) => void;
-        scope: Scope;
-        weight: number;
+        separator?: never;
+    }
+    /**
+     * A representation of a menu separator item in contextmenu.ts.
+     */
+    export interface SeparatorContextMenuOption extends CoreContextMenuOption {
+        separator: true;
+        text?: never;
+        enabled?: never;
+        callback?: never;
     }
+    /**
+     * A menu item as presented to contextmenu.ts.
+     */
+    export type ContextMenuOption = ActionContextMenuOption | SeparatorContextMenuOption;
     /**
      * A subset of ContextMenuOption corresponding to what was publicly
      * documented.  ContextMenuOption should be preferred for new code.
      */
-    interface LegacyContextMenuOption {
+    export interface LegacyContextMenuOption {
         text: string;
         enabled: boolean;
         callback: (p1: Scope) => void;
+        separator?: never;
     }
+    export {};
 }
 export type ScopeType = ContextMenuRegistry.ScopeType;
 export declare const ScopeType: typeof ContextMenuRegistry.ScopeType;

package/core/dragging/block_drag_strategy.d.ts

@@ -25,8 +25,8 @@ export declare class BlockDragStrategy implements IDragStrategy {
      * block, to add to the drag location. In workspace units.
      */
     private dragOffset;
-    /** Was there already an event group in progress when the drag started? */
-    private inGroup;
+    /** Used to persist an event group when snapping is done async. */
+    private originalEventGroup;
     constructor(block: BlockSvg);
     /** Returns true if the block is currently movable. False otherwise. */
     isMovable(): boolean;
@@ -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/dragging/bubble_drag_strategy.d.ts

@@ -10,8 +10,6 @@ export declare class BubbleDragStrategy implements IDragStrategy {
     private bubble;
     private workspace;
     private startLoc;
-    /** Was there already an event group in progress when the drag started? */
-    private inGroup;
     constructor(bubble: IBubble, workspace: WorkspaceSvg);
     isMovable(): boolean;
     startDrag(): void;

package/core/dragging/comment_drag_strategy.d.ts

@@ -10,8 +10,6 @@ export declare class CommentDragStrategy implements IDragStrategy {
     private comment;
     private startLoc;
     private workspace;
-    /** Was there already an event group in progress when the drag started? */
-    private inGroup;
     constructor(comment: RenderedWorkspaceComment);
     isMovable(): boolean;
     startDrag(): void;

package/core/field.d.ts

@@ -54,8 +54,6 @@ export declare abstract class Field<T = any> implements IASTNodeLocationSvg, IAS
      * `FieldImage.prototype.DEFAULT_VALUE = null;`
      */
     DEFAULT_VALUE: T | null;
-    /** Non-breaking space. */
-    static readonly NBSP = "\u00A0";
     /**
      * A value used to signal when a field's constructor should *not* set the
      * field's value or run configure_, and should allow a subclass to do that
@@ -205,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
@@ -662,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_dropdown.d.ts

@@ -10,13 +10,10 @@ import { MenuItem } from './menuitem.js';
  * Class for an editable dropdown field.
  */
 export declare class FieldDropdown extends Field<string> {
-    /** Horizontal distance that a checkmark overhangs the dropdown. */
-    static CHECKMARK_OVERHANG: number;
     /**
-     * Maximum height of the dropdown menu, as a percentage of the viewport
-     * height.
+     * Magic constant used to represent a separator in a list of dropdown items.
      */
-    static MAX_MENU_HEIGHT_VH: number;
+    static readonly SEPARATOR = "separator";
     static ARROW_CHAR: string;
     /** A reference to the currently selected menu item. */
     private selectedMenuItem;
@@ -239,11 +236,12 @@ export interface ImageProperties {
     height: number;
 }
 /**
- * An individual option in the dropdown menu. The first element is the human-
- * readable value (text or image), and the second element is the language-
- * neutral value.
+ * An individual option in the dropdown menu. Can be either the string literal
+ * `separator` for a menu separator item, or an array for normal action menu
+ * items. In the latter case, the first element is the human-readable value
+ * (text or image), and the second element is the language-neutral value.
  */
-export type MenuOption = [string | ImageProperties, string];
+export type MenuOption = [string | ImageProperties, string] | 'separator';
 /**
  * A function that generates an array of menu options for FieldDropdown
  * or its descendants.

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_flyout_inflater.d.ts

@@ -1,5 +1,5 @@
 import type { FlyoutItem } from '../flyout_item.js';
-import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { IFlyout } from './i_flyout.js';
 export interface IFlyoutInflater {
     /**
      * Loads the object represented by the given state onto the workspace.
@@ -8,14 +8,14 @@ export interface IFlyoutInflater {
      * allow for code reuse.
      *
      * @param state A JSON representation of an element to inflate on the flyout.
-     * @param flyoutWorkspace The flyout's workspace, where the inflated element
+     * @param flyout The flyout on whose workspace the inflated element
      *    should be created. If the inflated element is an `IRenderedElement` it
      *    itself or the inflater should append it to the workspace; the flyout
      *    will not do so itself. The flyout is responsible for positioning the
      *    element, however.
      * @returns The newly inflated flyout element.
      */
-    load(state: object, flyoutWorkspace: WorkspaceSvg): FlyoutItem;
+    load(state: object, flyout: IFlyout): FlyoutItem;
     /**
      * Returns the amount of spacing that should follow the element corresponding
      * to the given JSON representation.