blockly 12.0.1-beta.1 → 12.1.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/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/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

@@ -67,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.
      *
@@ -83,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;
     /**
@@ -133,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;
@@ -155,6 +177,10 @@ export declare class FocusManager {
      * simultaneously will result in an error being thrown).
      */
     takeEphemeralFocus(focusableElement: HTMLElement | SVGElement): ReturnEphemeralFocus;
+    /**
+     * @returns whether something is currently holding ephemeral focus
+     */
+    ephemeralFocusTaken(): boolean;
     /**
      * Ensures that the manager is currently allowing operations that change its
      * internal focus state (such as via focusNode()).

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.
  */
@@ -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_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.1-beta.1",
+  "version": "12.1.0",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"