blockly 11.2.0-beta.0 → 11.2.0-beta.1

package/core/bubbles/textinput_bubble.d.ts

@@ -42,6 +42,7 @@ export declare class TextInputBubble extends Bubble {
     private readonly DEFAULT_SIZE;
     /** The minimum size of this bubble, including borders. */
     private readonly MIN_SIZE;
+    private editable;
     /**
      * @param workspace The workspace this bubble belongs to.
      * @param anchor The anchor location of the thing this bubble is attached to.
@@ -54,6 +55,10 @@ export declare class TextInputBubble extends Bubble {
     getText(): string;
     /** Sets the text of this bubble. Calls change listeners. */
     setText(text: string): void;
+    /** Sets whether or not the text in the bubble is editable. */
+    setEditable(editable: boolean): void;
+    /** Returns whether or not the text in the bubble is editable. */
+    isEditable(): boolean;
     /** Adds a change listener to be notified when this bubble's text changes. */
     addTextChangeListener(listener: () => void): void;
     /** Adds a change listener to be notified when this bubble's size changes. */

package/core/connection.d.ts

@@ -102,11 +102,11 @@ export declare class Connection implements IASTNodeLocationWithBlock {
      * Called when an attempted connection fails. NOP by default (i.e. for
      * headless workspaces).
      *
-     * @param _otherConnection Connection that this connection failed to connect
-     *     to.
+     * @param _superiorConnection Connection that this connection failed to connect
+     *     to. The provided connection should be the superior connection.
      * @internal
      */
-    onFailedConnect(_otherConnection: Connection): void;
+    onFailedConnect(_superiorConnection: Connection): void;
     /**
      * Connect this connection to another connection.
      *

package/core/field_dropdown.d.ts

@@ -54,6 +54,13 @@ export declare class FieldDropdown extends Field<string> {
     suffixField: string | null;
     private selectedOption;
     clickTarget_: SVGElement | null;
+    /**
+     * The y offset from the top of the field to the top of the image, if an image
+     * is selected.
+     */
+    protected static IMAGE_Y_OFFSET: number;
+    /** The total vertical padding above and below an image. */
+    protected static IMAGE_Y_PADDING: number;
     /**
      * @param menuGenerator A non-empty array of options for a dropdown list, or a
      *     function which generates these options. Also accepts Field.SKIP_SETUP
@@ -196,6 +203,33 @@ export declare class FieldDropdown extends Field<string> {
      * @internal
      */
     static fromJson(options: FieldDropdownFromJsonConfig): FieldDropdown;
+    /**
+     * Factor out common words in statically defined options.
+     * Create prefix and/or suffix labels.
+     */
+    protected trimOptions(options: MenuOption[]): {
+        options: MenuOption[];
+        prefix?: string;
+        suffix?: string;
+    };
+    /**
+     * Use the calculated prefix and suffix lengths to trim all of the options in
+     * the given array.
+     *
+     * @param options Array of option tuples:
+     *     (human-readable text or image, language-neutral name).
+     * @param prefixLength The length of the common prefix.
+     * @param suffixLength The length of the common suffix
+     * @returns A new array with all of the option text trimmed.
+     */
+    private applyTrim;
+    /**
+     * Validates the data structure to be processed as an options list.
+     *
+     * @param options The proposed dropdown options.
+     * @throws {TypeError} If proposed options are incorrectly structured.
+     */
+    protected validateOptions(options: MenuOption[]): void;
 }
 /**
  * Definition of a human-readable image dropdown option.

package/core/icons/comment_icon.d.ts

@@ -22,10 +22,8 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
      * weight values are rendered farther toward the end of the block.
      */
     static readonly WEIGHT = 3;
-    /** The bubble used to show editable text to the user. */
+    /** The bubble used to show comment text to the user. */
     private textInputBubble;
-    /** The bubble used to show non-editable text to the user. */
-    private textBubble;
     /** The text of this comment. */
     private text;
     /** The size of this comment (which is applied to the editable bubble). */
@@ -90,6 +88,7 @@ export declare class CommentIcon extends Icon implements IHasBubble, ISerializab
     private showEditableBubble;
     /** Shows the non editable text bubble for this comment. */
     private showNonEditableBubble;
+    protected createBubble(): void;
     /** Hides any open bubbles owned by this comment. */
     private hideBubble;
     /**

package/core/rendered_connection.d.ts

@@ -60,10 +60,15 @@ export declare class RenderedConnection extends Connection {
      * Move the block(s) belonging to the connection to a point where they don't
      * visually interfere with the specified connection.
      *
-     * @param staticConnection The connection to move away from.
+     * @param superiorConnection The connection to move away from. The provided
+     *     connection should be the superior connection and should not be
+     *     connected to this connection.
+     * @param initiatedByThis Whether or not the block group that was manipulated
+     *     recently causing bump checks is associated with the inferior
+     *     connection. Defaults to false.
      * @internal
      */
-    bumpAwayFrom(staticConnection: RenderedConnection): void;
+    bumpAwayFrom(superiorConnection: RenderedConnection, initiatedByThis?: boolean): void;
     /**
      * Change the connection's coordinates.
      *
@@ -162,11 +167,11 @@ export declare class RenderedConnection extends Connection {
      * Bumps this connection away from the other connection. Called when an
      * attempted connection fails.
      *
-     * @param otherConnection Connection that this connection failed to connect
-     *     to.
+     * @param superiorConnection Connection that this connection failed to connect
+     *     to. The provided connection should be the superior connection.
      * @internal
      */
-    onFailedConnect(otherConnection: Connection): void;
+    onFailedConnect(superiorConnection: Connection): void;
     /**
      * Disconnect two blocks that are connected by this connection.
      *

package/core/shortcut_registry.d.ts

@@ -30,13 +30,13 @@ export declare class ShortcutRegistry {
      * Registers a keyboard shortcut.
      *
      * @param shortcut The shortcut for this key code.
-     * @param opt_allowOverrides True to prevent a warning when overriding an
+     * @param allowOverrides True to prevent a warning when overriding an
      *     already registered item.
      * @throws {Error} if a shortcut with the same name already exists.
      */
-    register(shortcut: KeyboardShortcut, opt_allowOverrides?: boolean): void;
+    register(shortcut: KeyboardShortcut, allowOverrides?: boolean): void;
     /**
-     * Unregisters a keyboard shortcut registered with the given key code. This
+     * Unregisters a keyboard shortcut registered with the given name. This
      * will also remove any key mappings that reference this shortcut.
      *
      * @param shortcutName The name of the shortcut to unregister.
@@ -46,16 +46,23 @@ export declare class ShortcutRegistry {
     /**
      * Adds a mapping between a keycode and a keyboard shortcut.
      *
+     * Normally only one shortcut can be mapped to any given keycode,
+     * but setting allowCollisions to true allows a keyboard to be
+     * mapped to multiple shortcuts.  In that case, when onKeyDown is
+     * called with the given keystroke, it will process the mapped
+     * shortcuts in reverse order, from the most- to least-recently
+     * mapped).
+     *
      * @param keyCode The key code for the keyboard shortcut. If registering a key
      *     code with a modifier (ex: ctrl+c) use
      *     ShortcutRegistry.registry.createSerializedKey;
      * @param shortcutName The name of the shortcut to execute when the given
      *     keycode is pressed.
-     * @param opt_allowCollision True to prevent an error when adding a shortcut
+     * @param allowCollision True to prevent an error when adding a shortcut
      *     to a key that is already mapped to a shortcut.
      * @throws {Error} if the given key code is already mapped to a shortcut.
      */
-    addKeyMapping(keyCode: string | number | KeyCodes, shortcutName: string, opt_allowCollision?: boolean): void;
+    addKeyMapping(keyCode: string | number | KeyCodes, shortcutName: string, allowCollision?: boolean): void;
     /**
      * Removes a mapping between a keycode and a keyboard shortcut.
      *
@@ -64,11 +71,11 @@ export declare class ShortcutRegistry {
      *     ShortcutRegistry.registry.createSerializedKey;
      * @param shortcutName The name of the shortcut to execute when the given
      *     keycode is pressed.
-     * @param opt_quiet True to not console warn when there is no shortcut to
+     * @param quiet True to not console warn when there is no shortcut to
      *     remove.
      * @returns True if a key mapping was removed, false otherwise.
      */
-    removeKeyMapping(keyCode: string, shortcutName: string, opt_quiet?: boolean): boolean;
+    removeKeyMapping(keyCode: string, shortcutName: string, quiet?: boolean): boolean;
     /**
      * Removes all the key mappings for a shortcut with the given name.
      * Useful when changing the default key mappings and the key codes registered
@@ -105,6 +112,21 @@ export declare class ShortcutRegistry {
     /**
      * Handles key down events.
      *
+     * - Any `KeyboardShortcut`(s) mapped to the keycodes that cause
+     *   event `e` to be fired will be processed, in order from least-
+     *   to most-recently registered.
+     * - If the shortcut's `preconditionFn` exists it will be called.
+     *   If `preconditionFn` returns false the shortcut's `callback`
+     *   function will be skipped.  Processing will continue with the
+     *   next shortcut, if any.
+     * - The shortcut's `callback` function will then be called.  If it
+     *   returns true, processing will terminate and `onKeyDown` will
+     *   return true.  If it returns false, processing will continue
+     *   with with the next shortcut, if any.
+     * - If all registered shortcuts for the given keycode have been
+     *   processed without any having returned true, `onKeyDown` will
+     *   return false.
+     *
      * @param workspace The main workspace where the event was captured.
      * @param e The key down event.
      * @returns True if the event was handled, false otherwise.
@@ -145,18 +167,56 @@ export declare class ShortcutRegistry {
      *
      * @param keyCode Number code representing the key.
      * @param modifiers List of modifier key codes to be used with the key. All
-     *     valid modifiers can be found in the ShortcutRegistry.modifierKeys.
+     *     valid modifiers can be found in the `ShortcutRegistry.modifierKeys`.
      * @returns The serialized key code for the given modifiers and key.
      */
     createSerializedKey(keyCode: number, modifiers: KeyCodes[] | null): string;
 }
 export declare namespace ShortcutRegistry {
+    /** Interface defining a keyboard shortcut. */
     interface KeyboardShortcut {
-        callback?: (p1: WorkspaceSvg, p2: Event, p3: KeyboardShortcut) => boolean;
+        /**
+         * The function to be called when the shorctut is invoked.
+         *
+         * @param workspace The `WorkspaceSvg` when the shortcut was
+         *     invoked.
+         * @param e The event that caused the shortcut to be activated.
+         * @param shortcut The `KeyboardShortcut` that was activated
+         *     (i.e., the one this callback is attached to).
+         * @returns Returning true ends processing of the invoked keycode.
+         *     Returning false causes processing to continue with the
+         *     next-most-recently registered shortcut for the invoked
+         *     keycode.
+         */
+        callback?: (workspace: WorkspaceSvg, e: Event, shortcut: KeyboardShortcut) => boolean;
+        /** The name of the shortcut.  Should be unique. */
         name: string;
-        preconditionFn?: (p1: WorkspaceSvg) => boolean;
+        /**
+         * A function to be called when the shortcut is invoked, before
+         * calling `callback`, to decide if this shortcut is applicable in
+         * the current situation.
+         *
+         * @param workspace The `WorkspaceSvg` where the shortcut was
+         *     invoked.
+         * @returns True iff `callback` function should be called.
+         */
+        preconditionFn?: (workspace: WorkspaceSvg) => boolean;
+        /** Optional arbitray extra data attached to the shortcut. */
         metadata?: object;
+        /**
+         * Optional list of key codes to be bound (via
+         * ShortcutRegistry.prototype.addKeyMapping) to this shortcut.
+         */
         keyCodes?: (number | string)[];
+        /**
+         * Value of `allowCollision` to pass to `addKeyMapping` when
+         * binding this shortcut's `.keyCodes` (if any).
+         *
+         * N.B.: this is only used for binding keycodes at the time this
+         * shortcut is initially registered, not for any subsequent
+         * `addKeyMapping` calls that happen to reference this shortcut's
+         * name.
+         */
         allowCollision?: boolean;
     }
     /** Supported modifiers. */

package/core/utils/drag.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WorkspaceSvg } from '../workspace_svg.js';
+import { Coordinate } from './coordinate.js';
+/**
+ * Start tracking a drag of an object on this workspace by recording the offset
+ * between the pointer's current location and the object's starting location.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer down event.
+ * @param xy Starting location of object.
+ */
+export declare function start(workspace: WorkspaceSvg, e: PointerEvent, xy: Coordinate): void;
+/**
+ * Compute the new position of a dragged object in this workspace based on the
+ * current pointer position and the offset between the pointer's starting
+ * location and the object's starting location.
+ *
+ * The start function should have be called previously, when the drag started.
+ *
+ * Used for resizing block comments and workspace comments.
+ *
+ * @param workspace The workspace where the drag is occurring.
+ * @param e Pointer move event.
+ * @returns New location of object.
+ */
+export declare function move(workspace: WorkspaceSvg, e: PointerEvent): Coordinate;
+//# sourceMappingURL=drag.d.ts.map

package/core/utils/rect.d.ts

@@ -10,6 +10,7 @@
  *
  * @class
  */
+import { Coordinate } from './coordinate.js';
 /**
  * Class for representing rectangular regions.
  */
@@ -25,7 +26,15 @@ export declare class Rect {
      * @param right Right.
      */
     constructor(top: number, bottom: number, left: number, right: number);
+    /**
+     * Creates a new copy of this rectangle.
+     *
+     * @returns A copy of this Rect.
+     */
+    clone(): Rect;
+    /** Returns the height of this rectangle. */
     getHeight(): number;
+    /** Returns the width of this rectangle. */
     getWidth(): number;
     /**
      * Tests whether this rectangle contains a x/y coordinate.
@@ -43,5 +52,22 @@ export declare class Rect {
      * @returns Whether this rectangle intersects the provided rectangle.
      */
     intersects(other: Rect): boolean;
+    /**
+     * Compares bounding rectangles for equality.
+     *
+     * @param a A Rect.
+     * @param b A Rect.
+     * @returns True iff the bounding rectangles are equal, or if both are null.
+     */
+    static equals(a?: Rect | null, b?: Rect | null): boolean;
+    /**
+     * Creates a new Rect using a position and supplied dimensions.
+     *
+     * @param position The upper left coordinate of the new rectangle.
+     * @param width The width of the rectangle, in pixels.
+     * @param height The height of the rectangle, in pixels.
+     * @returns A newly created Rect using the provided Coordinate and dimensions.
+     */
+    static createFromPoint(position: Coordinate, width: number, height: number): Rect;
 }
 //# sourceMappingURL=rect.d.ts.map

package/core/workspace_svg.d.ts

@@ -138,8 +138,6 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
     startScrollX: number;
     /** Vertical scroll value when scrolling started in pixel units. */
     startScrollY: number;
-    /** Distance from mouse to object being dragged. */
-    private dragDeltaXY;
     /** Current scale. */
     scale: number;
     /** Cached scale value. Used to detect changes in viewport. */
@@ -704,7 +702,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      *     blocks on the workspace.
      */
     getBlocksBoundingBox(): Rect;
-    /** Clean up the workspace by ordering all the blocks in a column. */
+    /** Clean up the workspace by ordering all the blocks in a column such that none overlap. */
     cleanUp(): void;
     /**
      * Show the context menu for the workspace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockly",
-  "version": "11.2.0-beta.0",
+  "version": "11.2.0-beta.1",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"
@@ -78,11 +78,11 @@
     "@typescript-eslint/parser": "^8.1.0",
     "async-done": "^2.0.0",
     "chai": "^5.1.1",
-    "concurrently": "^8.0.1",
+    "concurrently": "^9.0.1",
     "eslint": "^8.4.1",
     "eslint-config-google": "^0.14.0",
     "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-jsdoc": "^48.0.2",
+    "eslint-plugin-jsdoc": "^50.4.3",
     "glob": "^10.3.4",
     "google-closure-compiler": "^20240317.0.0",
     "gulp": "^5.0.0",
@@ -110,7 +110,7 @@
     "yargs": "^17.2.1"
   },
   "dependencies": {
-    "jsdom": "25.0.0"
+    "jsdom": "25.0.1"
   },
   "engines": {
     "node": ">=18"