blockly 12.2.0-beta.0 → 12.2.0

package/core/clipboard.d.ts

@@ -9,11 +9,83 @@ import type { ICopyData, ICopyable } from './interfaces/i_copyable.js';
 import { Coordinate } from './utils/coordinate.js';
 import { WorkspaceSvg } from './workspace_svg.js';
 /**
- * Private version of copy for stubbing in tests.
+ * Copy a copyable item, and record its data and the workspace it was
+ * copied from.
+ *
+ * This function does not perform any checks to ensure the copy
+ * should be allowed, e.g. to ensure the block is deletable. Such
+ * checks should be done before calling this function.
+ *
+ * Note that if the copyable item is not an `ISelectable` or its
+ * `workspace` property is not a `WorkspaceSvg`, the copy will be
+ * successful, but there will be no saved workspace data. This will
+ * impact the ability to paste the data unless you explictily pass
+ * a workspace into the paste method.
+ *
+ * @param toCopy item to copy.
+ * @param location location to save as a potential paste location.
+ * @returns the copied data if copy was successful, otherwise null.
+ */
+export declare function copy<T extends ICopyData>(toCopy: ICopyable<T>, location?: Coordinate): T | null;
+/**
+ * Gets the copy data for the last item copied. This is useful if you
+ * are implementing custom copy/paste behavior. If you want the default
+ * behavior, just use the copy and paste methods directly.
+ *
+ * @returns copy data for the last item copied, or null if none set.
+ */
+export declare function getLastCopiedData(): ICopyable.ICopyData | null;
+/**
+ * Sets the last copied item. You should call this method if you implement
+ * custom copy behavior, so that other callers are working with the correct
+ * data. This method is called automatically if you use the built-in copy
+ * method.
+ *
+ * @param copyData copy data for the last item copied.
+ */
+export declare function setLastCopiedData(copyData: ICopyData): void;
+/**
+ * Gets the workspace that was last copied from. This is useful if you
+ * are implementing custom copy/paste behavior and want to paste on the
+ * same workspace that was copied from. If you want the default behavior,
+ * just use the copy and paste methods directly.
+ *
+ * @returns workspace that was last copied from, or null if none set.
  */
-declare function copyInternal<T extends ICopyData>(toCopy: ICopyable<T>): T | null;
+export declare function getLastCopiedWorkspace(): WorkspaceSvg | null;
 /**
- * Paste a pasteable element into the workspace.
+ * Sets the workspace that was last copied from. You should call this method
+ * if you implement custom copy behavior, so that other callers are working
+ * with the correct data. This method is called automatically if you use the
+ * built-in copy method.
+ *
+ * @param workspace workspace that was last copied from.
+ */
+export declare function setLastCopiedWorkspace(workspace: WorkspaceSvg): void;
+/**
+ * Gets the location that was last copied from. This is useful if you
+ * are implementing custom copy/paste behavior. If you want the
+ * default behavior, just use the copy and paste methods directly.
+ *
+ * @returns last saved location, or null if none set.
+ */
+export declare function getLastCopiedLocation(): Coordinate | undefined;
+/**
+ * Sets the location that was last copied from. You should call this method
+ * if you implement custom copy behavior, so that other callers are working
+ * with the correct data. This method is called automatically if you use the
+ * built-in copy method.
+ *
+ * @param location last saved location, which can be used to paste at.
+ */
+export declare function setLastCopiedLocation(location: Coordinate): void;
+/**
+ * Paste a pasteable element into the given workspace.
+ *
+ * This function does not perform any checks to ensure the paste
+ * is allowed, e.g. that the workspace is rendered or the block
+ * is pasteable. Such checks should be done before calling this
+ * function.
  *
  * @param copyData The data to paste into the workspace.
  * @param workspace The workspace to paste the data into.
@@ -22,21 +94,10 @@ declare function copyInternal<T extends ICopyData>(toCopy: ICopyable<T>): T | nu
  */
 export declare function paste<T extends ICopyData>(copyData: T, workspace: WorkspaceSvg, coordinate?: Coordinate): ICopyable<T> | null;
 /**
- * Pastes the last copied ICopyable into the workspace.
+ * Pastes the last copied ICopyable into the last copied-from workspace.
  *
  * @returns the pasted thing if the paste was successful, null otherwise.
  */
 export declare function paste(): ICopyable<ICopyData> | null;
-/**
- * Private version of duplicate for stubbing in tests.
- */
-declare function duplicateInternal<U extends ICopyData, T extends ICopyable<U> & IHasWorkspace>(toDuplicate: T): T | null;
-interface IHasWorkspace {
-    workspace: WorkspaceSvg;
-}
-export declare const TEST_ONLY: {
-    duplicateInternal: typeof duplicateInternal;
-    copyInternal: typeof copyInternal;
-};
 export { BlockCopyData, BlockPaster, registry };
 //# sourceMappingURL=clipboard.d.ts.map

package/core/comments/collapse_comment_bar_button.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { CommentBarButton } from './comment_bar_button.js';
+/**
+ * Magic string appended to the comment ID to create a unique ID for this button.
+ */
+export declare const COMMENT_COLLAPSE_BAR_BUTTON_FOCUS_IDENTIFIER = "_collapse_bar_button";
+/**
+ * Button that toggles the collapsed state of a comment.
+ */
+export declare class CollapseCommentBarButton extends CommentBarButton {
+    protected readonly id: string;
+    protected readonly workspace: WorkspaceSvg;
+    protected readonly container: SVGGElement;
+    /**
+     * Opaque ID used to unbind event handlers during disposal.
+     */
+    private readonly bindId;
+    /**
+     * SVG image displayed on this button.
+     */
+    protected readonly icon: SVGImageElement;
+    /**
+     * Creates a new CollapseCommentBarButton instance.
+     *
+     * @param id The ID of this button's parent comment.
+     * @param workspace The workspace this button's parent comment is displayed on.
+     * @param container An SVG group that this button should be a child of.
+     */
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement);
+    /**
+     * Disposes of this button.
+     */
+    dispose(): void;
+    /**
+     * Adjusts the positioning of this button within its container.
+     */
+    reposition(): void;
+    /**
+     * Toggles the collapsed state of the parent comment.
+     *
+     * @param e The event that triggered this action.
+     */
+    performAction(e?: Event): void;
+}
+//# sourceMappingURL=collapse_comment_bar_button.d.ts.map

package/core/comments/comment_bar_button.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
+import { Rect } from '../utils/rect.js';
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import type { RenderedWorkspaceComment } from './rendered_workspace_comment.js';
+/**
+ * Button displayed on a comment's top bar.
+ */
+export declare abstract class CommentBarButton implements IFocusableNode {
+    protected readonly id: string;
+    protected readonly workspace: WorkspaceSvg;
+    protected readonly container: SVGGElement;
+    /**
+     * SVG image displayed on this button.
+     */
+    protected abstract readonly icon: SVGImageElement;
+    /**
+     * Creates a new CommentBarButton instance.
+     *
+     * @param id The ID of this button's parent comment.
+     * @param workspace The workspace this button's parent comment is on.
+     * @param container An SVG group that this button should be a child of.
+     */
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement);
+    /**
+     * Returns whether or not this button is currently visible.
+     */
+    isVisible(): boolean;
+    /**
+     * Returns the parent comment of this comment bar button.
+     */
+    getParentComment(): RenderedWorkspaceComment;
+    /** Adjusts the position of this button within its parent container. */
+    abstract reposition(): void;
+    /** Perform the action this button should take when it is acted on. */
+    abstract performAction(e?: Event): void;
+    /**
+     * Returns the dimensions of this button in workspace coordinates.
+     *
+     * @param includeMargin True to include the margin when calculating the size.
+     * @returns The size of this button.
+     */
+    getSize(includeMargin?: boolean): Rect;
+    /** Returns the margin in workspace coordinates surrounding this button. */
+    getMargin(): number;
+    /** Returns a DOM element representing this button that can receive focus. */
+    getFocusableElement(): SVGImageElement;
+    /** Returns the workspace this button is a child of. */
+    getFocusableTree(): WorkspaceSvg;
+    /** Called when this button's focusable DOM element gains focus. */
+    onNodeFocus(): void;
+    /** Called when this button's focusable DOM element loses focus. */
+    onNodeBlur(): void;
+    /** Returns whether this button can be focused. True if it is visible. */
+    canBeFocused(): boolean;
+}
+//# sourceMappingURL=comment_bar_button.d.ts.map

package/core/comments/comment_view.d.ts

@@ -8,23 +8,24 @@ import { IRenderedElement } from '../interfaces/i_rendered_element.js';
 import { Coordinate } from '../utils/coordinate.js';
 import { Size } from '../utils/size.js';
 import { WorkspaceSvg } from '../workspace_svg.js';
+import { CommentBarButton } from './comment_bar_button.js';
 export declare class CommentView implements IRenderedElement {
     readonly workspace: WorkspaceSvg;
-    private commentId?;
+    private commentId;
     /** The root group element of the comment view. */
     private svgRoot;
     /**
-     * The svg rect element that we use to create a hightlight around the comment.
+     * The SVG rect element that we use to create a highlight around the comment.
      */
     private highlightRect;
     /** The group containing all of the top bar elements. */
     private topBarGroup;
     /** The rect background for the top bar. */
     private topBarBackground;
-    /** The delete icon that goes in the top bar. */
-    private deleteIcon;
-    /** The foldout icon that goes in the top bar. */
-    private foldoutIcon;
+    /** The delete button that goes in the top bar. */
+    private deleteButton;
+    /** The foldout button that goes in the top bar. */
+    private foldoutButton;
     /** The text element that goes in the top bar. */
     private textPreview;
     /** The actual text node in the text preview. */
@@ -65,7 +66,7 @@ export declare class CommentView implements IRenderedElement {
     private preResizeSize?;
     /** The default size of newly created comments. */
     static defaultCommentSize: Size;
-    constructor(workspace: WorkspaceSvg, commentId?: string | undefined);
+    constructor(workspace: WorkspaceSvg, commentId: string);
     /**
      * Creates the rect we use for highlighting the comment when it's selected.
      */
@@ -112,22 +113,10 @@ export declare class CommentView implements IRenderedElement {
      * The minimum height is based on the height of the top bar.
      */
     private calcMinSize;
-    /** Calculates the margin that should exist around the delete icon. */
-    private calcDeleteMargin;
-    /** Calculates the margin that should exist around the foldout icon. */
-    private calcFoldoutMargin;
     /** Updates the size of the highlight rect to reflect the new size. */
     private updateHighlightRect;
     /** Updates the size of the top bar to reflect the new size. */
     private updateTopBarSize;
-    /**
-     * Updates the position of the delete icon elements to reflect the new size.
-     */
-    private updateDeleteIconPosition;
-    /**
-     * Updates the position of the foldout icon elements to reflect the new size.
-     */
-    private updateFoldoutIconPosition;
     /**
      * Updates the size and position of the text preview elements to reflect the new size.
      */
@@ -170,11 +159,6 @@ export declare class CommentView implements IRenderedElement {
     addOnCollapseListener(listener: (newCollapse: boolean) => void): void;
     /** Removes the given listener from the list of on collapse listeners. */
     removeOnCollapseListener(listener: () => void): void;
-    /**
-     * Toggles the collapsedness of the block when we receive a pointer down
-     * event on the foldout icon.
-     */
-    private onFoldoutDown;
     /** Returns true if the comment is currently editable. */
     isEditable(): boolean;
     /** Sets the editability of the comment. */
@@ -202,7 +186,7 @@ export declare class CommentView implements IRenderedElement {
     /** Truncates the text to fit within the top view. */
     private truncateText;
     /** Brings the workspace comment to the front of its layer. */
-    private bringToFront;
+    bringToFront(): void;
     /**
      * Handles disposing of the comment when we get a pointer down event on the
      * delete icon.
@@ -221,5 +205,9 @@ export declare class CommentView implements IRenderedElement {
     addDisposeListener(listener: () => void): void;
     /** Removes the given listener from the list of disposal listeners. */
     removeDisposeListener(listener: () => void): void;
+    /**
+     * @internal
+     */
+    getCommentBarButtons(): CommentBarButton[];
 }
 //# sourceMappingURL=comment_view.d.ts.map

package/core/comments/delete_comment_bar_button.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { CommentBarButton } from './comment_bar_button.js';
+/**
+ * Magic string appended to the comment ID to create a unique ID for this button.
+ */
+export declare const COMMENT_DELETE_BAR_BUTTON_FOCUS_IDENTIFIER = "_delete_bar_button";
+/**
+ * Button that deletes a comment.
+ */
+export declare class DeleteCommentBarButton extends CommentBarButton {
+    protected readonly id: string;
+    protected readonly workspace: WorkspaceSvg;
+    protected readonly container: SVGGElement;
+    /**
+     * Opaque ID used to unbind event handlers during disposal.
+     */
+    private readonly bindId;
+    /**
+     * SVG image displayed on this button.
+     */
+    protected readonly icon: SVGImageElement;
+    /**
+     * Creates a new DeleteCommentBarButton instance.
+     *
+     * @param id The ID of this button's parent comment.
+     * @param workspace The workspace this button's parent comment is shown on.
+     * @param container An SVG group that this button should be a child of.
+     */
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement);
+    /**
+     * Disposes of this button.
+     */
+    dispose(): void;
+    /**
+     * Adjusts the positioning of this button within its container.
+     */
+    reposition(): void;
+    /**
+     * Deletes parent comment.
+     *
+     * @param e The event that triggered this action.
+     */
+    performAction(e?: Event): void;
+}
+//# sourceMappingURL=delete_comment_bar_button.d.ts.map

package/core/comments.d.ts

@@ -3,8 +3,11 @@
  * Copyright 2024 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+export { CollapseCommentBarButton } from './comments/collapse_comment_bar_button.js';
+export { CommentBarButton } from './comments/comment_bar_button.js';
 export { CommentEditor } from './comments/comment_editor.js';
 export { CommentView } from './comments/comment_view.js';
+export { DeleteCommentBarButton } from './comments/delete_comment_bar_button.js';
 export { RenderedWorkspaceComment } from './comments/rendered_workspace_comment.js';
 export { WorkspaceComment } from './comments/workspace_comment.js';
 //# sourceMappingURL=comments.d.ts.map

package/core/field_input.d.ts

@@ -48,8 +48,8 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
     protected valueWhenEditorWasOpened_: string | T | null;
     /** Key down event data. */
     private onKeyDownWrapper;
-    /** Key input event data. */
-    private onKeyInputWrapper;
+    /** Input element input event data. */
+    private onInputWrapper;
     /**
      * Whether the field should consider the whole parent block to be its click
      * target.
@@ -204,7 +204,7 @@ export declare abstract class FieldInput<T extends InputTypes> extends Field<str
     /**
      * Handle a change to the editor.
      *
-     * @param _e Keyboard event.
+     * @param _e InputEvent.
      */
     private onHtmlInputChange;
     /**

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/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/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.
      *