blockly 11.2.0-beta.0 → 11.2.0-beta.2

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.
@@ -132,31 +154,69 @@ export declare class ShortcutRegistry {
      * @param e A key down event.
      * @returns The serialized key code for the given event.
      */
-    private serializeKeyEvent_;
+    private serializeKeyEvent;
     /**
      * Checks whether any of the given modifiers are not valid.
      *
      * @param modifiers List of modifiers to be used with the key.
      * @throws {Error} if the modifier is not in the valid modifiers list.
      */
-    private checkModifiers_;
+    private checkModifiers;
     /**
      * Creates the serialized key code that will be used in the key map.
      *
      * @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/theme_manager.d.ts

@@ -19,7 +19,7 @@ export declare class ThemeManager {
     private readonly workspace;
     private theme;
     /** A list of workspaces that are subscribed to this theme. */
-    private subscribedWorkspaces_;
+    private subscribedWorkspaces;
     private componentDB;
     /**
      * @param workspace The main workspace.

package/core/toolbox/category.d.ts

@@ -143,7 +143,7 @@ export declare class ToolboxCategory extends ToolboxItem implements ISelectableT
      * @param styleName Name of the style.
      * @returns The hex colour for the category.
      */
-    private getColourfromStyle_;
+    private getColourfromStyle;
     /**
      * Gets the HTML element that is clickable.
      * The parent toolbox element receives clicks. The parent toolbox will add an
@@ -160,7 +160,7 @@ export declare class ToolboxCategory extends ToolboxItem implements ISelectableT
      *     reference string pointing to one of those two values.
      * @returns The hex colour for the category.
      */
-    private parseColour_;
+    private parseColour;
     /**
      * Adds appropriate classes to display an open icon.
      *

package/core/toolbox/collapsible_category.d.ts

@@ -40,7 +40,7 @@ export declare class CollapsibleToolboxCategory extends ToolboxCategory implemen
      *
      * @param itemDef The information needed to create a toolbox item.
      */
-    private createToolboxItem_;
+    private createToolboxItem;
     init(): void;
     createDom_(): HTMLDivElement;
     createIconDom_(): HTMLSpanElement;

package/core/toolbox/separator.d.ts

@@ -15,7 +15,7 @@ export declare class ToolboxSeparator extends ToolboxItem {
     static registrationName: string;
     /** All the CSS class names that are used to create a separator. */
     protected cssConfig_: CssConfig;
-    private htmlDiv_;
+    private htmlDiv;
     /**
      * @param separatorDef The information needed to create a separator.
      * @param toolbox The parent toolbox for the separator.

package/core/toolbox/toolbox.d.ts

@@ -29,7 +29,7 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      */
     id: string;
     protected toolboxDef_: toolbox.ToolboxInfo;
-    private readonly horizontalLayout_;
+    private readonly horizontalLayout;
     /** The HTML container for the toolbox. */
     HtmlDiv: HTMLDivElement | null;
     /** The HTML container for the contents of a toolbox. */
@@ -44,7 +44,7 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
     protected height_: number;
     RTL: boolean;
     /** The flyout for the toolbox. */
-    private flyout_;
+    private flyout;
     protected contentMap_: {
         [key: string]: IToolboxItem;
     };
@@ -140,7 +140,7 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      *     the toolbox.
      * @param fragment The document fragment to add the child toolbox elements to.
      */
-    private createToolboxItem_;
+    private createToolboxItem;
     /**
      * Adds an item to the toolbox.
      *
@@ -364,32 +364,32 @@ export declare class Toolbox extends DeleteArea implements IAutoHideable, IKeybo
      * @param oldItem The previously selected toolbox item.
      * @param newItem The newly selected toolbox item.
      */
-    private fireSelectEvent_;
+    private fireSelectEvent;
     /**
      * Closes the current item if it is expanded, or selects the parent.
      *
      * @returns True if a parent category was selected, false otherwise.
      */
-    private selectParent_;
+    private selectParent;
     /**
      * Selects the first child of the currently selected item, or nothing if the
      * toolbox item has no children.
      *
      * @returns True if a child category was selected, false otherwise.
      */
-    private selectChild_;
+    private selectChild;
     /**
      * Selects the next visible toolbox item.
      *
      * @returns True if a next category was selected, false otherwise.
      */
-    private selectNext_;
+    private selectNext;
     /**
      * Selects the previous visible toolbox item.
      *
      * @returns True if a previous category was selected, false otherwise.
      */
-    private selectPrevious_;
+    private selectPrevious;
     /** Disposes of this toolbox. */
     dispose(): void;
 }

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/variable_map.d.ts

@@ -54,7 +54,7 @@ export declare class VariableMap {
      * @param newName New variable name.
      * @param blocks The list of all blocks in the workspace.
      */
-    private renameVariableAndUses_;
+    private renameVariableAndUses;
     /**
      * Update the name of the given variable to the same name as an existing
      * variable.  The two variables are coalesced into a single variable with the
@@ -66,7 +66,7 @@ export declare class VariableMap {
      * @param conflictVar The variable that was already using newName.
      * @param blocks The list of all blocks in the workspace.
      */
-    private renameVariableWithConflict_;
+    private renameVariableWithConflict;
     /**
      * Create a variable with a given name, optional type, and optional ID.
      *

package/core/variable_model.d.ts

@@ -20,7 +20,7 @@ export declare class VariableModel {
     workspace: Workspace;
     name: string;
     type: string;
-    private readonly id_;
+    private readonly id;
     /**
      * @param workspace The variable's workspace.
      * @param name The name of the variable.  This is the user-visible name (e.g.

package/core/workspace.d.ts

@@ -107,7 +107,7 @@ export declare class Workspace implements IASTNodeLocation {
      * @returns The comparison value. This tells Array.sort() how to change object
      *     a's index.
      */
-    private sortObjects_;
+    private sortObjects;
     /**
      * Adds a block to the list of top blocks.
      *

package/core/workspace_audio.d.ts

@@ -12,7 +12,7 @@ export declare class WorkspaceAudio {
     /** Database of pre-loaded sounds. */
     private sounds;
     /** Time that the last sound was played. */
-    private lastSound_;
+    private lastSound;
     /** Whether the audio is muted or not. */
     private muted;
     /**

package/core/workspace_dragger.d.ts

@@ -12,8 +12,8 @@ import type { WorkspaceSvg } from './workspace_svg.js';
  */
 export declare class WorkspaceDragger {
     private workspace;
-    private readonly horizontalScrollEnabled_;
-    private readonly verticalScrollEnabled_;
+    private readonly horizontalScrollEnabled;
+    private readonly verticalScrollEnabled;
     protected startScrollXY_: Coordinate;
     /** @param workspace The workspace to drag. */
     constructor(workspace: WorkspaceSvg);

package/core/workspace_svg.d.ts

@@ -66,7 +66,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * Whether the workspace is visible.  False if the workspace has been hidden
      * by calling `setVisible(false)`.
      */
-    private isVisible_;
+    private visible;
     /**
      * Whether this workspace has resizes enabled.
      * Disable during batch operations for a performance improvement.
@@ -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. */
@@ -160,7 +158,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * Category-based toolbox providing blocks which may be dragged into this
      * workspace.
      */
-    private toolbox_;
+    private toolbox;
     /**
      * The current gesture in progress on this workspace, if any.
      *
@@ -342,7 +340,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      *
      * @param blocks List of blocks to update the style on.
      */
-    private updateBlockStyles_;
+    private updateBlockStyles;
     /**
      * Getter for the inverted screen CTM.
      *
@@ -471,7 +469,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * Update items that use screen coordinate calculations
      * because something has changed (e.g. scroll position, window size).
      */
-    private updateScreenCalculations_;
+    private updateScreenCalculations;
     /**
      * If enabled, resize the parts of the workspace that change when the
      * workspace contents (e.g. block positions) change.  This will also scroll
@@ -639,7 +637,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      *
      * @param e Pointer down event.
      */
-    private onMouseDown_;
+    private onMouseDown;
     /**
      * Start tracking a drag of an object on this workspace.
      *
@@ -695,7 +693,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      *
      * @param e Mouse wheel event.
      */
-    private onMouseWheel_;
+    private onMouseWheel;
     /**
      * Calculate the bounding box for the blocks on the workspace.
      * Coordinate system: workspace coordinates.
@@ -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.
@@ -976,7 +974,7 @@ export declare class WorkspaceSvg extends Workspace implements IASTNodeLocationS
      * @param xyRatio Contains an x and/or y property which is a float between 0
      *     and 1 specifying the degree of scrolling.
      */
-    private static setTopLevelWorkspaceMetrics_;
+    private static setTopLevelWorkspaceMetrics;
 }
 /**
  * Size the workspace when the contents change.  This also updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockly",
-  "version": "11.2.0-beta.0",
+  "version": "11.2.0-beta.2",
   "description": "Blockly is a library for building visual programming editors.",
   "keywords": [
     "blockly"
@@ -74,16 +74,16 @@
     "@hyperjump/json-schema": "^1.5.0",
     "@microsoft/api-documenter": "^7.22.4",
     "@microsoft/api-extractor": "^7.29.5",
-    "@typescript-eslint/eslint-plugin": "^8.1.0",
-    "@typescript-eslint/parser": "^8.1.0",
     "async-done": "^2.0.0",
     "chai": "^5.1.1",
-    "concurrently": "^8.0.1",
-    "eslint": "^8.4.1",
+    "concurrently": "^9.0.1",
+    "eslint": "^9.15.0",
     "eslint-config-google": "^0.14.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-jsdoc": "^48.0.2",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^50.5.0",
+    "eslint-plugin-prettier": "^5.2.1",
     "glob": "^10.3.4",
+    "globals": "^15.12.0",
     "google-closure-compiler": "^20240317.0.0",
     "gulp": "^5.0.0",
     "gulp-concat": "^2.6.1",
@@ -106,11 +106,12 @@
     "readline-sync": "^1.4.10",
     "rimraf": "^5.0.0",
     "typescript": "^5.3.3",
+    "typescript-eslint": "^8.16.0",
     "webdriverio": "^9.0.7",
     "yargs": "^17.2.1"
   },
   "dependencies": {
-    "jsdom": "25.0.0"
+    "jsdom": "25.0.1"
   },
   "engines": {
     "node": ">=18"