blockly 12.2.0 → 12.3.0-beta.0

package/core/block.d.ts

@@ -544,7 +544,7 @@ export declare class Block {
      *
      * @yields A generator that can be used to iterate the fields on the block.
      */
-    getFields(): Generator<Field>;
+    getFields(): Generator<Field, undefined, void>;
     /**
      * Return all variables referenced by this block.
      *

package/core/block_svg.d.ts

@@ -361,9 +361,12 @@ export declare class BlockSvg extends Block implements IBoundedElement, IContext
     /**
      * Encode a block for copying.
      *
+     * @param addNextBlocks If true, copy subsequent blocks attached to this one
+     *     as well.
+     *
      * @returns Copy metadata, or null if the block is an insertion marker.
      */
-    toCopyData(): BlockCopyData | null;
+    toCopyData(addNextBlocks?: boolean): BlockCopyData | null;
     /**
      * Updates the colour of the block to match the block's state.
      *

package/core/bubbles/bubble.d.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { IBubble } from '../interfaces/i_bubble.js';
+import type { IFocusableNode } from '../interfaces/i_focusable_node.js';
 import type { IFocusableTree } from '../interfaces/i_focusable_tree.js';
+import type { IHasBubble } from '../interfaces/i_has_bubble.js';
 import { ISelectable } from '../interfaces/i_selectable.js';
 import { Coordinate } from '../utils/coordinate.js';
 import { Rect } from '../utils/rect.js';
@@ -15,10 +17,11 @@ import { WorkspaceSvg } from '../workspace_svg.js';
  * bubble, where it has a "tail" that points to the block, and a "head" that
  * displays arbitrary svg elements.
  */
-export declare abstract class Bubble implements IBubble, ISelectable {
+export declare abstract class Bubble implements IBubble, ISelectable, IFocusableNode {
     readonly workspace: WorkspaceSvg;
     protected anchor: Coordinate;
     protected ownerRect?: Rect | undefined;
+    protected owner?: (IHasBubble & IFocusableNode) | undefined;
     /** The width of the border around the bubble. */
     static readonly BORDER_WIDTH = 6;
     /** Double the width of the border around the bubble. */
@@ -72,8 +75,9 @@ export declare abstract class Bubble implements IBubble, ISelectable {
      *     element that's represented by this bubble (as a focusable node). This
      *     element will have its ID overwritten. If not provided, the focusable
      *     element of this node will default to the bubble's SVG root.
+     * @param owner The object responsible for hosting/spawning this bubble.
      */
-    constructor(workspace: WorkspaceSvg, anchor: Coordinate, ownerRect?: Rect | undefined, overriddenFocusableElement?: SVGElement | HTMLElement);
+    constructor(workspace: WorkspaceSvg, anchor: Coordinate, ownerRect?: Rect | undefined, overriddenFocusableElement?: SVGElement | HTMLElement, owner?: (IHasBubble & IFocusableNode) | undefined);
     /** Dispose of this bubble. */
     dispose(): void;
     /**
@@ -107,6 +111,13 @@ export declare abstract class Bubble implements IBubble, ISelectable {
      * is focused.
      */
     private onMouseDown;
+    /**
+     * Handles key events when this bubble is focused. By default, closes the
+     * bubble on Escape.
+     *
+     * @param e The keyboard event to handle.
+     */
+    protected onKeyDown(e: KeyboardEvent): void;
     /** Positions the bubble relative to its anchor. Does not render its tail. */
     protected positionRelativeToAnchor(): void;
     /**
@@ -209,5 +220,9 @@ export declare abstract class Bubble implements IBubble, ISelectable {
     onNodeBlur(): void;
     /** See IFocusableNode.canBeFocused. */
     canBeFocused(): boolean;
+    /**
+     * Returns the object that owns/hosts this bubble, if any.
+     */
+    getOwner(): (IHasBubble & IFocusableNode) | undefined;
 }
 //# sourceMappingURL=bubble.d.ts.map

package/core/bubbles/textinput_bubble.d.ts

@@ -3,6 +3,9 @@
  * Copyright 2023 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 { IHasBubble } from '../interfaces/i_has_bubble.js';
 import { Coordinate } from '../utils/coordinate.js';
 import { Rect } from '../utils/rect.js';
 import { Size } from '../utils/size.js';
@@ -16,10 +19,7 @@ export declare class TextInputBubble extends Bubble {
     readonly workspace: WorkspaceSvg;
     protected anchor: Coordinate;
     protected ownerRect?: Rect | undefined;
-    /** The root of the elements specific to the text element. */
-    private inputRoot;
-    /** The text input area element. */
-    private textArea;
+    protected owner?: (IHasBubble & IFocusableNode) | undefined;
     /** The group containing the lines indicating the bubble is resizable. */
     private resizeGroup;
     /**
@@ -32,27 +32,26 @@ export declare class TextInputBubble extends Bubble {
      * resize group.
      */
     private resizePointerMoveListener;
-    /** Functions listening for changes to the text of this bubble. */
-    private textChangeListeners;
     /** Functions listening for changes to the size of this bubble. */
     private sizeChangeListeners;
     /** Functions listening for changes to the location of this bubble. */
     private locationChangeListeners;
-    /** The text of this bubble. */
-    private text;
     /** The default size of this bubble, including borders. */
     private readonly DEFAULT_SIZE;
     /** The minimum size of this bubble, including borders. */
     private readonly MIN_SIZE;
     private editable;
+    /** View responsible for supporting text editing. */
+    private editor;
     /**
      * @param workspace The workspace this bubble belongs to.
      * @param anchor The anchor location of the thing this bubble is attached to.
      *     The tail of the bubble will point to this location.
      * @param ownerRect An optional rect we don't want the bubble to overlap with
      *     when automatically positioning.
+     * @param owner The object that owns/hosts this bubble.
      */
-    constructor(workspace: WorkspaceSvg, anchor: Coordinate, ownerRect?: Rect | undefined);
+    constructor(workspace: WorkspaceSvg, anchor: Coordinate, ownerRect?: Rect | undefined, owner?: (IHasBubble & IFocusableNode) | undefined);
     /** @returns the text of this bubble. */
     getText(): string;
     /** Sets the text of this bubble. Calls change listeners. */
@@ -67,12 +66,6 @@ export declare class TextInputBubble extends Bubble {
     addSizeChangeListener(listener: () => void): void;
     /** Adds a change listener to be notified when this bubble's location changes. */
     addLocationChangeListener(listener: () => void): void;
-    /** Creates and returns the editable text area for this bubble's editor. */
-    private static createTextArea;
-    /** Creates and returns the UI container element for this bubble's editor. */
-    private createEditor;
-    /** Binds events to the text area element. */
-    private bindTextAreaEvents;
     /** Creates the resize handler elements and binds events to them. */
     private createResizeHandle;
     /**
@@ -95,11 +88,15 @@ export declare class TextInputBubble extends Bubble {
     private onResizePointerUp;
     /** Handles pointer move events on the resize target. */
     private onResizePointerMove;
-    /** Handles a text change event for the text area. Calls event listeners. */
-    private onTextChange;
     /** Handles a size change event for the text area. Calls event listeners. */
     private onSizeChange;
     /** Handles a location change event for the text area. Calls event listeners. */
     private onLocationChange;
+    /**
+     * Returns the text editor component of this bubble.
+     *
+     * @internal
+     */
+    getEditor(): CommentEditor;
 }
 //# sourceMappingURL=textinput_bubble.d.ts.map

package/core/comments/collapse_comment_bar_button.d.ts

@@ -5,6 +5,7 @@
  */
 import type { WorkspaceSvg } from '../workspace_svg.js';
 import { CommentBarButton } from './comment_bar_button.js';
+import type { CommentView } from './comment_view.js';
 /**
  * Magic string appended to the comment ID to create a unique ID for this button.
  */
@@ -16,6 +17,7 @@ export declare class CollapseCommentBarButton extends CommentBarButton {
     protected readonly id: string;
     protected readonly workspace: WorkspaceSvg;
     protected readonly container: SVGGElement;
+    protected readonly commentView: CommentView;
     /**
      * Opaque ID used to unbind event handlers during disposal.
      */
@@ -31,7 +33,7 @@ export declare class CollapseCommentBarButton extends CommentBarButton {
      * @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);
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement, commentView: CommentView);
     /**
      * Disposes of this button.
      */

package/core/comments/comment_bar_button.d.ts

@@ -6,7 +6,7 @@
 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';
+import type { CommentView } from './comment_view.js';
 /**
  * Button displayed on a comment's top bar.
  */
@@ -14,6 +14,7 @@ export declare abstract class CommentBarButton implements IFocusableNode {
     protected readonly id: string;
     protected readonly workspace: WorkspaceSvg;
     protected readonly container: SVGGElement;
+    protected readonly commentView: CommentView;
     /**
      * SVG image displayed on this button.
      */
@@ -25,15 +26,15 @@ export declare abstract class CommentBarButton implements IFocusableNode {
      * @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);
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement, commentView: CommentView);
     /**
      * Returns whether or not this button is currently visible.
      */
     isVisible(): boolean;
     /**
-     * Returns the parent comment of this comment bar button.
+     * Returns the parent comment view of this comment bar button.
      */
-    getParentComment(): RenderedWorkspaceComment;
+    getCommentView(): CommentView;
     /** 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. */

package/core/comments/comment_view.d.ts

@@ -11,7 +11,7 @@ import { WorkspaceSvg } from '../workspace_svg.js';
 import { CommentBarButton } from './comment_bar_button.js';
 export declare class CommentView implements IRenderedElement {
     readonly workspace: WorkspaceSvg;
-    private commentId;
+    readonly commentId: string;
     /** The root group element of the comment view. */
     private svgRoot;
     /**

package/core/comments/delete_comment_bar_button.d.ts

@@ -5,6 +5,7 @@
  */
 import type { WorkspaceSvg } from '../workspace_svg.js';
 import { CommentBarButton } from './comment_bar_button.js';
+import type { CommentView } from './comment_view.js';
 /**
  * Magic string appended to the comment ID to create a unique ID for this button.
  */
@@ -16,6 +17,7 @@ export declare class DeleteCommentBarButton extends CommentBarButton {
     protected readonly id: string;
     protected readonly workspace: WorkspaceSvg;
     protected readonly container: SVGGElement;
+    protected readonly commentView: CommentView;
     /**
      * Opaque ID used to unbind event handlers during disposal.
      */
@@ -31,7 +33,7 @@ export declare class DeleteCommentBarButton extends CommentBarButton {
      * @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);
+    constructor(id: string, workspace: WorkspaceSvg, container: SVGGElement, commentView: CommentView);
     /**
      * Disposes of this button.
      */

package/core/icons/comment_icon.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Block } from '../block.js';
-import type { IBubble } from '../interfaces/i_bubble.js';
+import { TextInputBubble } from '../bubbles/textinput_bubble.js';
 import type { IHasBubble } from '../interfaces/i_has_bubble.js';
 import type { ISerializable } from '../interfaces/i_serializable.js';
 import { Coordinate } from '../utils.js';
@@ -34,7 +34,7 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
     /**
      * The visibility of the bubble for this comment.
      *
-     * This is used to track what the visibile state /should/ be, not necessarily
+     * This is used to track what the visible state /should/ be, not necessarily
      * what it currently /is/. E.g. sometimes this will be true, but the block
      * hasn't been rendered yet, so the bubble will not currently be visible.
      */
@@ -94,7 +94,7 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
     bubbleIsVisible(): boolean;
     setBubbleVisible(visible: boolean): Promise<void>;
     /** See IHasBubble.getBubble. */
-    getBubble(): IBubble | null;
+    getBubble(): TextInputBubble | null;
     /**
      * Shows the editable text bubble for this comment, and adds change listeners
      * to update the state of this icon in response to changes in the bubble.

package/core/insertion_marker_previewer.d.ts

@@ -6,6 +6,7 @@
 import { BlockSvg } from './block_svg.js';
 import { IConnectionPreviewer } from './interfaces/i_connection_previewer.js';
 import { RenderedConnection } from './rendered_connection.js';
+import * as blocks from './serialization/blocks.js';
 export declare class InsertionMarkerPreviewer implements IConnectionPreviewer {
     private readonly workspace;
     private fadedBlock;
@@ -36,6 +37,16 @@ export declare class InsertionMarkerPreviewer implements IConnectionPreviewer {
     previewConnection(draggedConn: RenderedConnection, staticConn: RenderedConnection): void;
     private shouldUseMarkerPreview;
     private previewMarker;
+    /**
+     * Transforms the given block into a JSON representation used to construct an
+     * insertion marker.
+     *
+     * @param block The block to serialize and use as an insertion marker.
+     * @returns A JSON-formatted string corresponding to a serialized
+     *     representation of the given block suitable for use as an insertion
+     *     marker.
+     */
+    protected serializeBlockToInsertionMarker(block: BlockSvg): blocks.State;
     private createInsertionMarker;
     /**
      * Gets the connection on the marker block that matches the original

package/core/interfaces/i_variable_map.d.ts

@@ -34,7 +34,7 @@ export interface IVariableMap<T extends IVariableModel<IVariableState>> {
      * Creates a new variable with the given name. If ID is not specified, the
      * variable map should create one. Returns the new variable.
      */
-    createVariable(name: string, id?: string, type?: string | null): T;
+    createVariable(name: string, type?: string, id?: string | null): T;
     addVariable(variable: T): void;
     /**
      * Changes the name of the given variable to the name provided and returns the

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockly",
-  "version": "12.2.0",
+  "version": "12.3.0-beta.0",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"
@@ -67,24 +67,25 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "@blockly/block-test": "^7.0.1",
-    "@blockly/dev-tools": "^9.0.0",
-    "@blockly/theme-modern": "^6.0.3",
+    "@blockly/block-test": "^7.0.2",
+    "@blockly/dev-tools": "^9.0.2",
+    "@blockly/theme-modern": "^7.0.1",
     "@hyperjump/browser": "^1.1.4",
     "@hyperjump/json-schema": "^1.5.0",
-    "@microsoft/api-documenter": "^7.22.4",
+    "@microsoft/api-documenter": "7.22.4",
     "@microsoft/api-extractor": "^7.29.5",
+    "ajv": "^8.17.1",
     "async-done": "^2.0.0",
     "chai": "^5.1.1",
     "concurrently": "^9.0.1",
     "eslint": "^9.15.0",
     "eslint-config-google": "^0.14.0",
     "eslint-config-prettier": "^10.1.1",
-    "eslint-plugin-jsdoc": "^51.3.1",
+    "eslint-plugin-jsdoc": "^52.0.2",
     "eslint-plugin-prettier": "^5.2.1",
     "glob": "^11.0.1",
     "globals": "^16.0.0",
-    "google-closure-compiler": "^20250625.0.0",
+    "google-closure-compiler": "^20250709.0.0",
     "gulp": "^5.0.0",
     "gulp-concat": "^2.6.1",
     "gulp-gzip": "^1.4.2",