blockly 12.2.0-beta.0 → 12.3.0-beta.0

package/core/keyboard_nav/block_comment_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TextInputBubble } from '../bubbles/textinput_bubble.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 TextInputBubble.
+ */
+export declare class BlockCommentNavigationPolicy implements INavigationPolicy<TextInputBubble> {
+    /**
+     * Returns the first child of the given block comment.
+     *
+     * @param current The block comment to return the first child of.
+     * @returns The text editor of the given block comment bubble.
+     */
+    getFirstChild(current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the parent of the given block comment.
+     *
+     * @param current The block comment to return the parent of.
+     * @returns The parent block of the given block comment.
+     */
+    getParent(current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given block comment.
+     *
+     * @param _current The block comment to find the following element of.
+     * @returns Null.
+     */
+    getNextSibling(_current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given block comment.
+     *
+     * @param _current The block comment to find the preceding element of.
+     * @returns Null.
+     */
+    getPreviousSibling(_current: TextInputBubble): IFocusableNode | null;
+    /**
+     * Returns whether or not the given block comment can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given block comment can be focused.
+     */
+    isNavigable(current: TextInputBubble): 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 TextInputBubble.
+     */
+    isApplicable(current: any): current is TextInputBubble;
+}
+//# sourceMappingURL=block_comment_navigation_policy.d.ts.map

package/core/keyboard_nav/block_navigation_policy.d.ts

@@ -8,6 +8,7 @@ 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 type { ISelectable } from '../interfaces/i_selectable.js';
 import { RenderedConnection } from '../rendered_connection.js';
 /**
  * Set of rules controlling keyboard navigation from a block.
@@ -60,17 +61,17 @@ 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.
+ * Returns the next/previous stack relative to the given element's stack.
  *
- * @param current The block whose stack will be navigated relative to.
+ * @param current The element 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.
+ * @returns The first element in the stack offset by `delta` relative to the
+ *     current element's stack, or the last element in the stack offset by
+ * `delta` relative to the current element's stack when navigating backwards.
  */
-export declare function navigateStacks(current: BlockSvg, delta: number): BlockSvg | null;
+export declare function navigateStacks(current: ISelectable, delta: number): IFocusableNode | null;
 /**
  * Returns the next navigable item relative to the provided block child.
  *

package/core/keyboard_nav/comment_bar_button_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentBarButton } from '../comments/comment_bar_button.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 a CommentBarButton.
+ */
+export declare class CommentBarButtonNavigationPolicy implements INavigationPolicy<CommentBarButton> {
+    /**
+     * Returns the first child of the given CommentBarButton.
+     *
+     * @param _current The CommentBarButton to return the first child of.
+     * @returns Null.
+     */
+    getFirstChild(_current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the parent of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to return the parent of.
+     * @returns The parent comment of the given CommentBarButton.
+     */
+    getParent(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to find the following element of.
+     * @returns The next CommentBarButton, if any.
+     */
+    getNextSibling(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given CommentBarButton.
+     *
+     * @param current The CommentBarButton to find the preceding element of.
+     * @returns The CommentBarButton's previous CommentBarButton, if any.
+     */
+    getPreviousSibling(current: CommentBarButton): IFocusableNode | null;
+    /**
+     * Returns whether or not the given CommentBarButton can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given CommentBarButton can be focused.
+     */
+    isNavigable(current: CommentBarButton): 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 CommentBarButton.
+     */
+    isApplicable(current: any): current is CommentBarButton;
+}
+//# sourceMappingURL=comment_bar_button_navigation_policy.d.ts.map

package/core/keyboard_nav/comment_editor_navigation_policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommentEditor } from '../comments/comment_editor.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 a comment editor.
+ * This is a no-op placeholder (other than isNavigable/isApplicable) since
+ * comment editors handle their own navigation when editing ends.
+ */
+export declare class CommentEditorNavigationPolicy implements INavigationPolicy<CommentEditor> {
+    getFirstChild(_current: CommentEditor): IFocusableNode | null;
+    getParent(_current: CommentEditor): IFocusableNode | null;
+    getNextSibling(_current: CommentEditor): IFocusableNode | null;
+    getPreviousSibling(_current: CommentEditor): IFocusableNode | null;
+    /**
+     * Returns whether or not the given comment editor can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns False.
+     */
+    isNavigable(current: CommentEditor): 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 a CommentEditor.
+     */
+    isApplicable(current: any): current is CommentEditor;
+}
+//# sourceMappingURL=comment_editor_navigation_policy.d.ts.map

package/core/keyboard_nav/line_cursor.d.ts

@@ -28,11 +28,11 @@ export declare class LineCursor extends Marker {
      */
     constructor(workspace: WorkspaceSvg);
     /**
-     * Moves the cursor to the next previous connection, next connection or block
-     * in the pre order traversal. Finds the next node in the pre order traversal.
+     * Moves the cursor to the next block or workspace comment in the pre-order
+     * traversal.
      *
-     * @returns The next node, or null if the current node is
-     *     not set or there is no next value.
+     * @returns The next node, or null if the current node is not set or there is
+     *     no next value.
      */
     next(): IFocusableNode | null;
     /**
@@ -44,11 +44,11 @@ export declare class LineCursor extends Marker {
      */
     in(): IFocusableNode | null;
     /**
-     * Moves the cursor to the previous next connection or previous connection in
-     * the pre order traversal.
+     * Moves the cursor to the previous block or workspace comment in the
+     * pre-order traversal.
      *
-     * @returns The previous node, or null if the current node
-     *     is not set or there is no previous value.
+     * @returns The previous node, or null if the current node is not set or there
+     *     is no previous value.
      */
     prev(): IFocusableNode | null;
     /**

package/core/keyboard_nav/workspace_comment_navigation_policy.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { RenderedWorkspaceComment } from '../comments/rendered_workspace_comment.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 RenderedWorkspaceComment.
+ */
+export declare class WorkspaceCommentNavigationPolicy implements INavigationPolicy<RenderedWorkspaceComment> {
+    /**
+     * Returns the first child of the given workspace comment.
+     *
+     * @param current The workspace comment to return the first child of.
+     * @returns The first child button of the given comment.
+     */
+    getFirstChild(current: RenderedWorkspaceComment): IFocusableNode | null;
+    /**
+     * Returns the parent of the given workspace comment.
+     *
+     * @param current The workspace comment to return the parent of.
+     * @returns The parent workspace of the given comment.
+     */
+    getParent(current: RenderedWorkspaceComment): IFocusableNode | null;
+    /**
+     * Returns the next peer node of the given workspace comment.
+     *
+     * @param current The workspace comment to find the following element of.
+     * @returns The next workspace comment or block stack, if any.
+     */
+    getNextSibling(current: RenderedWorkspaceComment): IFocusableNode | null;
+    /**
+     * Returns the previous peer node of the given workspace comment.
+     *
+     * @param current The workspace comment to find the preceding element of.
+     * @returns The previous workspace comment or block stack, if any.
+     */
+    getPreviousSibling(current: RenderedWorkspaceComment): IFocusableNode | null;
+    /**
+     * Returns whether or not the given workspace comment can be navigated to.
+     *
+     * @param current The instance to check for navigability.
+     * @returns True if the given workspace comment can be focused.
+     */
+    isNavigable(current: RenderedWorkspaceComment): 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 RenderedWorkspaceComment.
+     */
+    isApplicable(current: any): current is RenderedWorkspaceComment;
+}
+//# sourceMappingURL=workspace_comment_navigation_policy.d.ts.map

package/core/marker_manager.d.ts

@@ -8,7 +8,7 @@
  *
  * @class
  */
-import type { LineCursor } from './keyboard_nav/line_cursor.js';
+import { LineCursor } from './keyboard_nav/line_cursor.js';
 import type { Marker } from './keyboard_nav/marker.js';
 import type { WorkspaceSvg } from './workspace_svg.js';
 /**
@@ -45,7 +45,7 @@ export declare class MarkerManager {
      *
      * @returns The cursor for this workspace.
      */
-    getCursor(): LineCursor | null;
+    getCursor(): LineCursor;
     /**
      * Get a single marker that corresponds to the given ID.
      *

package/core/registry.d.ts

@@ -73,7 +73,7 @@ export declare class Type<_T> {
     static ICON: Type<IIcon>;
     /** @internal */
     static PASTER: Type<IPaster<ICopyable.ICopyData, ICopyable<ICopyable.ICopyData>>>;
-    static VARIABLE_MODEL: Type<IVariableModelStatic<IVariableState>>;
+    static VARIABLE_MODEL: Type<IVariableModelStatic<IVariableState> & IVariableModel<IVariableState>>;
     static VARIABLE_MAP: Type<IVariableMap<IVariableModel<IVariableState>>>;
 }
 /**

package/core/utils/focusable_tree_traverser.d.ts

@@ -41,8 +41,8 @@ export declare class FocusableTreeTraverser {
      * traversed but its nodes will never be returned here per the contract of
      * IFocusableTree.lookUpFocusableNode.
      *
-     * The provided element must have a non-null ID that conforms to the contract
-     * mentioned in IFocusableNode.
+     * The provided element must have a non-null, non-empty ID that conforms to
+     * the contract mentioned in IFocusableNode.
      *
      * @param element The HTML or SVG element being sought.
      * @param tree The tree under which the provided element may be a descendant.

package/core/utils/rect.d.ts

@@ -26,6 +26,13 @@ export declare class Rect {
      * @param right Right.
      */
     constructor(top: number, bottom: number, left: number, right: number);
+    /**
+     * Converts a DOM or SVG Rect to a Blockly Rect.
+     *
+     * @param rect The rectangle to convert.
+     * @returns A representation of the same rectangle as a Blockly Rect.
+     */
+    static from(rect: DOMRect | SVGRect): Rect;
     /**
      * Creates a new copy of this rectangle.
      *
@@ -36,6 +43,8 @@ export declare class Rect {
     getHeight(): number;
     /** Returns the width of this rectangle. */
     getWidth(): number;
+    /** Returns the top left coordinate of this rectangle. */
+    getOrigin(): Coordinate;
     /**
      * Tests whether this rectangle contains a x/y coordinate.
      *

package/core/workspace.d.ts

@@ -13,6 +13,7 @@ import type { Block } from './block.js';
 import { WorkspaceComment } from './comments/workspace_comment.js';
 import type { ConnectionDB } from './connection_db.js';
 import type { Abstract } from './events/events_abstract.js';
+import type { IBoundedElement } from './interfaces/i_bounded_element.js';
 import type { IConnectionChecker } from './interfaces/i_connection_checker.js';
 import { IProcedureMap } from './interfaces/i_procedure_map.js';
 import type { IVariableMap } from './interfaces/i_variable_map.js';
@@ -108,6 +109,15 @@ export declare class Workspace {
      *     a's index.
      */
     private sortObjects;
+    /**
+     * Sorts bounded elements on the workspace by their relative position, top to
+     * bottom (with slight LTR or RTL bias).
+     *
+     * @param a The first element to sort.
+     * @param b The second elment to sort.
+     * @returns -1, 0 or 1 depending on the sort order.
+     */
+    protected sortByOrigin(a: IBoundedElement, b: IBoundedElement): number;
     /**
      * Adds a block to the list of top blocks.
      *

package/core/workspace_svg.d.ts

@@ -14,6 +14,7 @@ import './events/events_viewport.js';
 import type { Block } from './block.js';
 import type { BlockSvg } from './block_svg.js';
 import * as browserEvents from './browser_events.js';
+import { RenderedWorkspaceComment } from './comments/rendered_workspace_comment.js';
 import { WorkspaceComment } from './comments/workspace_comment.js';
 import { ComponentManager } from './component_manager.js';
 import { ContextMenuOption } from './contextmenu_registry.js';
@@ -297,7 +298,7 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      *
      * @returns The cursor for the workspace.
      */
-    getCursor(): LineCursor | null;
+    getCursor(): LineCursor;
     /**
      * Get the block renderer attached to this workspace.
      *
@@ -850,13 +851,27 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      *
      * @param comment comment to add.
      */
-    addTopComment(comment: WorkspaceComment): void;
+    addTopComment(comment: RenderedWorkspaceComment): void;
     /**
      * Removes a comment from the list of top comments.
      *
      * @param comment comment to remove.
      */
-    removeTopComment(comment: WorkspaceComment): void;
+    removeTopComment(comment: RenderedWorkspaceComment): void;
+    /**
+     * Returns a list of comments on this workspace.
+     *
+     * @param ordered If true, sorts the comments based on their position.
+     * @returns A list of workspace comments.
+     */
+    getTopComments(ordered?: boolean): RenderedWorkspaceComment[];
+    /**
+     * Returns the workspace comment with the given ID, if any.
+     *
+     * @param id The ID of the comment to retrieve.
+     * @returns The workspace comment with the given ID, or null.
+     */
+    getCommentById(id: string): RenderedWorkspaceComment | null;
     getRootWorkspace(): WorkspaceSvg | null;
     /**
      * Adds a bounded element to the list of top bounded elements.
@@ -875,7 +890,7 @@ export declare class WorkspaceSvg extends Workspace implements IContextMenu, IFo
      *
      * @returns The top-level bounded elements.
      */
-    getTopBoundedElements(): IBoundedElement[];
+    getTopBoundedElements(ordered?: boolean): IBoundedElement[];
     /**
      * Update whether this workspace has resizes enabled.
      * If enabled, workspace will resize when appropriate.