scratch-blocks 2.0.0-spork.2 → 2.0.0-spork.3

package/src/scratch_connection_checker.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Blockly from "blockly/core";
+
+/**
+ * Custom connection checker to restrict which blocks can be connected.
+ */
+class ScratchConnectionChecker extends Blockly.ConnectionChecker {
+  /**
+   * Returns whether or not the two connections should be allowed to connect.
+   *
+   * @param a One of the connections to check.
+   * @param b The other connection to check.
+   * @param distance The maximum allowable distance between connections.
+   * @returns True if the connections should be allowed to connect.
+   */
+  doDragChecks(
+    a: Blockly.RenderedConnection,
+    b: Blockly.RenderedConnection,
+    distance: number
+  ): boolean {
+    // This check prevents dragging a block into the slot occupied by the
+    // procedure caller example block in a procedure definition block.
+    if (
+      b.getSourceBlock().type === "procedures_definition" &&
+      b.getParentInput()?.name === "custom_block"
+    ) {
+      return false;
+    }
+
+    return super.doDragChecks(a, b, distance);
+  }
+}
+
+Blockly.registry.register(
+  Blockly.registry.Type.CONNECTION_CHECKER,
+  Blockly.registry.DEFAULT,
+  ScratchConnectionChecker,
+  true
+);

package/src/{scratch_continuous_category.js → scratch_continuous_category.ts}

@@ -7,34 +7,41 @@
 import * as Blockly from "blockly/core";
 import { ContinuousCategory } from "@blockly/continuous-toolbox";
 
+type StatusIndicatorCategoryInfo = Blockly.utils.toolbox.CategoryInfo & {
+  showStatusButton?: string;
+};
+
+/**
+ * Selectable category shown in the Scratch toolbox.
+ */
 export class ScratchContinuousCategory extends ContinuousCategory {
   /**
    * Whether this toolbox category has a status indicator button on its label
    * in the flyout, typically for extensions that interface with hardware
    * devices.
-   * @type {boolean}
    */
-  showStatusButton = false;
+  private showStatusButton = false;
 
   /** Creates a new ScratchContinuousCategory.
    *
-   * @param {!Blockly.toolbox.CategoryInfo} toolboxItemDef A toolbox item
-   *     definition.
-   * @param {!Blockly.Toolbox} parentToolbox The toolbox this category is being
-   *     added to.
-   * @param {?Blockly.ICollapsibleToolboxItem} opt_parent The parent toolbox
-   *     category, if any.
+   * @param toolboxItemDef A toolbox item definition.
+   * @param parentToolbox The toolbox this category is being added to.
+   * @param opt_parent The parent toolbox category, if any.
    */
-  constructor(toolboxItemDef, parentToolbox, opt_parent) {
+  constructor(
+    toolboxItemDef: StatusIndicatorCategoryInfo,
+    parentToolbox: Blockly.Toolbox,
+    opt_parent?: Blockly.ICollapsibleToolboxItem
+  ) {
     super(toolboxItemDef, parentToolbox, opt_parent);
     this.showStatusButton = toolboxItemDef["showStatusButton"] === "true";
   }
 
   /**
    * Creates a DOM element for this category's icon.
-   * @returns {!HTMLElement} A DOM element for this category's icon.
+   * @returns A DOM element for this category's icon.
    */
-  createIconDom_() {
+  createIconDom_(): HTMLElement {
     if (this.toolboxItemDef_.iconURI) {
       const icon = document.createElement("img");
       icon.src = this.toolboxItemDef_.iconURI;
@@ -49,9 +56,9 @@ export class ScratchContinuousCategory extends ContinuousCategory {
 
   /**
    * Sets whether or not this category is selected.
-   * @param {boolean} isSelected True if this category is selected.
+   * @param isSelected True if this category is selected.
    */
-  setSelected(isSelected) {
+  setSelected(isSelected: boolean) {
     super.setSelected(isSelected);
     // Prevent hardcoding the background color to grey.
     this.rowDiv_.style.backgroundColor = "";

package/src/{scratch_continuous_toolbox.js → scratch_continuous_toolbox.ts}

@@ -6,23 +6,30 @@
 
 import * as Blockly from "blockly/core";
 import { ContinuousToolbox } from "@blockly/continuous-toolbox";
-import { ScratchContinuousCategory } from "./scratch_continuous_category.js";
+import { ScratchContinuousCategory } from "./scratch_continuous_category";
 
+/**
+ * A toolbox that displays items from all categories in one scrolling list.
+ */
 export class ScratchContinuousToolbox extends ContinuousToolbox {
-  postRenderCallbacks = [];
+  /**
+   * List of functions to run after the next time the toolbox renders.
+   */
+  private postRenderCallbacks: (() => void)[] = [];
 
   refreshSelection() {
-    // Intentionally a no-op, Scratch manually manages refreshing the toolbox via forceRerender().
+    // Intentionally a no-op, Scratch manually manages refreshing the toolbox
+    // via forceRerender().
   }
 
   /**
    * Gets the contents that should be shown in the flyout.
-   * @returns {!Blockly.utils.toolbox.FlyoutItemInfoArray} Flyout contents.
+   *
+   * @returns Flyout contents.
    */
-  getInitialFlyoutContents_() {
+  getInitialFlyoutContents_(): Blockly.utils.toolbox.FlyoutItemInfoArray {
     // TODO(#211) Clean this up when the continuous toolbox plugin is updated.
-    /** @type {!Blockly.utils.toolbox.FlyoutItemInfoArray} */
-    let contents = [];
+    let contents: Blockly.utils.toolbox.FlyoutItemInfoArray = [];
     for (const toolboxItem of this.getToolboxItems()) {
       if (toolboxItem instanceof ScratchContinuousCategory) {
         if (toolboxItem.shouldShowStatusButton()) {
@@ -35,19 +42,14 @@ export class ScratchContinuousToolbox extends ContinuousToolbox {
           // Create a label node to go at the top of the category
           contents.push({ kind: "LABEL", text: toolboxItem.getName() });
         }
-        /**
-         * @type {string|Blockly.utils.toolbox.FlyoutItemInfoArray|
-         *    Blockly.utils.toolbox.FlyoutItemInfo}
-         */
         let itemContents = toolboxItem.getContents();
 
         // Handle custom categories (e.g. variables and functions)
         if (typeof itemContents === "string") {
-          itemContents =
-            /** @type {!Blockly.utils.toolbox.DynamicCategoryInfo} */ ({
-              custom: itemContents,
-              kind: "CATEGORY",
-            });
+          itemContents = {
+            custom: itemContents,
+            kind: "CATEGORY",
+          };
         }
         contents = contents.concat(itemContents);
       }
@@ -70,9 +72,9 @@ export class ScratchContinuousToolbox extends ContinuousToolbox {
 
   /**
    * Runs the specified callback after the next rerender.
-   * @param {!Function} A callback to run whenever the toolbox next rerenders.
+   * @param callback A callback to run whenever the toolbox next rerenders.
    */
-  runAfterRerender(callback) {
+  runAfterRerender(callback: () => void) {
     this.postRenderCallbacks.push(callback);
   }
 }

package/src/{scratch_dragger.js → scratch_dragger.ts}

@@ -5,23 +5,44 @@
  */
 
 import * as Blockly from "blockly/core";
-import { BlockDragOutside } from "./events/events_block_drag_outside.js";
-import { BlockDragEnd } from "./events/events_block_drag_end.js";
+import { BlockDragOutside } from "./events/events_block_drag_outside";
+import { BlockDragEnd } from "./events/events_block_drag_end";
+import { isProcedureBlock, getCallers } from "./procedures";
 
+/**
+ * CSS class that allows the workspace to overflow its bounds when set.
+ */
 const BOUNDLESS_CLASS = "boundless";
 
-class ScratchDragger extends Blockly.dragging.Dragger {
-  constructor(draggable, workspace) {
-    super(draggable, workspace);
-    this.draggedOutOfBounds = false;
-    this.originatedFromFlyout = false;
-  }
+/**
+ * Class responsible for managing dragging items on the workspace.
+ */
+export class ScratchDragger extends Blockly.dragging.Dragger {
+  /**
+   * Whether or not the current drag location is outside of the main workspace.
+   */
+  draggedOutOfBounds = false;
+
+  /**
+   * Whether or not the current drag started from the flyout.
+   */
+  originatedFromFlyout = false;
 
-  setDraggable(draggable) {
+  /**
+   * Sets the current item being dragged.
+   *
+   * @param draggable The item being dragged.
+   */
+  setDraggable(draggable: Blockly.IDraggable) {
     this.draggable = draggable;
   }
 
-  onDragStart(event) {
+  /**
+   * Handles the start of a drag operation.
+   *
+   * @param event The event that triggered the drag.
+   */
+  onDragStart(event: PointerEvent) {
     super.onDragStart(event);
     if (this.draggable instanceof Blockly.BlockSvg) {
       this.workspace.addClass(BOUNDLESS_CLASS);
@@ -41,17 +62,28 @@ class ScratchDragger extends Blockly.dragging.Dragger {
     }
   }
 
-  onDrag(event, totalDelta) {
+  /**
+   * Handles motion during an ongoing drag operation.
+   *
+   * @param event The event that triggered this call.
+   * @param totalDelta The change in pointer position since the last invocation.
+   */
+  onDrag(event: PointerEvent, totalDelta: Blockly.utils.Coordinate) {
     super.onDrag(event, totalDelta);
     this.updateOutOfBoundsState(event);
   }
 
-  updateOutOfBoundsState(event) {
+  /**
+   * Records whether or not the current drag is out of the workspace's bounds.
+   *
+   * @param event The event that triggered this call.
+   */
+  updateOutOfBoundsState(event: PointerEvent) {
     if (this.draggable instanceof Blockly.BlockSvg) {
       const outOfBounds = !this.isInsideWorkspace(event);
       if (outOfBounds !== this.draggedOutOfBounds) {
         const event = new BlockDragOutside(
-          this.getDragRoot(this.draggable),
+          this.getDragRoot(this.draggable) as Blockly.BlockSvg,
           outOfBounds
         );
         Blockly.Events.fire(event);
@@ -60,18 +92,30 @@ class ScratchDragger extends Blockly.dragging.Dragger {
     }
   }
 
-  onDragEnd(event) {
+  /**
+   * Handles the end of a drag.
+   *
+   * @param event The event that ended the drag.
+   */
+  onDragEnd(event: PointerEvent) {
     if (
       this.draggable instanceof Blockly.BlockSvg &&
       this.draggable.type === "procedures_definition" &&
       this.wouldDeleteDraggable(event, this.draggable.getRootBlock())
     ) {
-      const procCode = this.draggable
-        .getInputTargetBlock("custom_block")
-        .getProcCode();
-      const hasCaller = this.workspace
-        .getBlocksByType("procedures_call")
-        .some((b) => b.getProcCode() === procCode);
+      const prototype = this.draggable
+        .getInput("custom_block")
+        .connection.targetBlock();
+      const hasCaller =
+        prototype instanceof Blockly.BlockSvg &&
+        isProcedureBlock(prototype) &&
+        getCallers(
+          prototype.getProcCode(),
+          this.draggable.workspace,
+          this.draggable.getRootBlock(),
+          false
+        ).length > 0;
+
       if (hasCaller) {
         Blockly.dialog.alert(Blockly.Msg.PROCEDURE_USED);
         this.draggable.revertDrag();
@@ -85,7 +129,7 @@ class ScratchDragger extends Blockly.dragging.Dragger {
     this.updateOutOfBoundsState(event);
     if (this.draggable instanceof Blockly.BlockSvg) {
       const event = new BlockDragEnd(
-        this.getDragRoot(this.draggable),
+        this.getDragRoot(this.draggable) as Blockly.BlockSvg,
         this.draggedOutOfBounds
       );
       Blockly.Events.fire(event);
@@ -95,14 +139,25 @@ class ScratchDragger extends Blockly.dragging.Dragger {
       // deleted.
       if (this.originatedFromFlyout && this.draggedOutOfBounds) {
         Blockly.renderManagement.finishQueuedRenders().then(() => {
-          this.getDragRoot(this.draggable).dispose();
+          const rootBlock = this.getDragRoot(this.draggable);
+          if (rootBlock instanceof Blockly.BlockSvg) {
+            rootBlock.dispose();
+          }
         });
       }
     }
     this.workspace.removeClass(BOUNDLESS_CLASS);
   }
 
-  shouldReturnToStart(event, rootDraggable) {
+  /**
+   * Returns whether or not the dragged item should return to its starting
+   * position.
+   *
+   * @param event The drag event that triggered this check.
+   * @param rootDraggable The topmost item being dragged.
+   * @returns True if the draggable should return to its starting position.
+   */
+  shouldReturnToStart(event: PointerEvent, rootDraggable: Blockly.IDraggable) {
     // If a block is dragged out of the workspace to be e.g. dropped on another
     // sprite, it should remain in the same place on the workspace where it was,
     // rather than being moved to an invisible part of the workspace.
@@ -111,18 +166,32 @@ class ScratchDragger extends Blockly.dragging.Dragger {
     );
   }
 
-  getDragRoot(block) {
+  /**
+   * Returns the root element being dragged. For shadow blocks, this is the
+   * parent block.
+   *
+   * @param draggable The element being dragged directly.
+   * @returns The element being dragged, or its parent.
+   */
+  getDragRoot(draggable: Blockly.IDraggable) {
     // We can't just use getRootBlock() here because, when blocks are detached
     // from a stack via dragging, getRootBlock() still returns the root of that
     // stack.
-    if (block.isShadow()) {
-      return block.getParent();
+    if (draggable instanceof Blockly.BlockSvg && draggable.isShadow()) {
+      return draggable.getParent();
     }
 
-    return block;
+    return draggable;
   }
 
-  isInsideWorkspace(event) {
+  /**
+   * Returns whether or not the given event occurred within the bounds of the
+   * workspace.
+   *
+   * @param event The event to check.
+   * @returns True if the event occurred inside the workspace.
+   */
+  isInsideWorkspace(event: PointerEvent) {
     const bounds = this.workspace.getParentSvg().getBoundingClientRect();
     const workspaceRect = new Blockly.utils.Rect(
       bounds.top,

package/src/{scratch_variable_map.js → scratch_variable_map.ts}

@@ -6,8 +6,11 @@
 
 import * as Blockly from "blockly/core";
 
+/**
+ * Class that provides storage for variables.
+ */
 class ScratchVariableMap extends Blockly.VariableMap {
-  getVariable(name, type) {
+  getVariable(name: string, type: string) {
     // Variable names in Blockly are case-insensitive, but case sensitive in
     // Scratch. Override the implementation to only return a variable whose name
     // is identical to the one requested.

package/src/scratch_variable_model.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as Blockly from "blockly/core";
+
+/**
+ * Class that represents a variable with extra fields for Scratch.
+ */
+export class ScratchVariableModel extends Blockly.VariableModel {
+  constructor(
+    workspace: Blockly.Workspace,
+    name: string,
+    type: string,
+    id: string,
+    public isLocal = false,
+    public isCloud = false
+  ) {
+    super(workspace, name, type, id);
+  }
+}
+
+Blockly.registry.register(
+  Blockly.registry.Type.VARIABLE_MODEL,
+  Blockly.registry.DEFAULT,
+  ScratchVariableModel,
+  true
+);

package/src/{shadows.js → shadows.ts}

@@ -5,9 +5,13 @@
  */
 
 import * as Blockly from "blockly/core";
-import { Colours } from "./colours.js";
+import { Colours } from "./colours";
 
-export function buildShadowFilter(workspace) {
+/**
+ * Creates an SVG filter to apply drop shadows to blocks being dragged and
+ * inserts it into the DOM.
+ */
+export function buildShadowFilter(workspace: Blockly.WorkspaceSvg) {
   const svg = workspace.getParentSvg();
   const defs = Blockly.utils.dom.createSvgElement(
     Blockly.utils.Svg.DEFS,
@@ -15,7 +19,7 @@ export function buildShadowFilter(workspace) {
     svg
   );
   // Adjust these width/height, x/y properties to stop the shadow from clipping
-  var dragShadowFilter = Blockly.utils.dom.createSvgElement(
+  const dragShadowFilter = Blockly.utils.dom.createSvgElement(
     "filter",
     {
       id: "blocklyDragShadowFilter",
@@ -34,7 +38,7 @@ export function buildShadowFilter(workspace) {
     },
     dragShadowFilter
   );
-  var componentTransfer = Blockly.utils.dom.createSvgElement(
+  const componentTransfer = Blockly.utils.dom.createSvgElement(
     "feComponentTransfer",
     { result: "offsetBlur" },
     dragShadowFilter

package/src/{status_indicator_label.js → status_indicator_label.ts}

@@ -33,42 +33,37 @@ import * as Blockly from "blockly/core";
 export class StatusIndicatorLabel extends Blockly.FlyoutButton {
   /**
    * The ID of the Scratch extension whose status is indicated by this label.
-   * @type {string}
    */
-  extensionId;
+  extensionId: string;
 
   /**
    * DOM element that displays the status indicator dot.
-   * @type {!SVGImageElement}
    */
-  imageElement;
+  imageElement: SVGImageElement;
 
   /**
    * Opaque data for mouse up listener used to unbind it in dispose().
-   * @type {!Blockly.browserEvents.Data}
    */
-  mouseUpwrapper;
+  mouseUpWrapper: Blockly.browserEvents.Data;
 
   /**
    * Function to be invoked when the status indicator is clicked.
-   * @type {?Function}
    */
-  static statusButtonCallback;
+  static statusButtonCallback: (extensionId: string) => void;
 
   /**
    * Creates a new StatusIndicatorLabel.
    *
-   * @param {!Blockly.WorkspaceSvg} workspace The workspace in which to place
-   *     this header.
-   * @param {!Blockly.WorkspaceSvg} targetWorkspace The flyout's target
-   *     workspace.
-   * @param {!Element} xml The XML specifying the header.
+   * @param workspace The workspace in which to place this header.
+   * @param targetWorkspace The flyout's target workspace.
+   * @param json The JSON specifying the header.
    */
-  constructor(workspace, targetWorkspace, json, isFlyoutLabel) {
-    super(workspace, targetWorkspace, json, isFlyoutLabel);
-    /**
-     * @type {string}
-     */
+  constructor(
+    workspace: Blockly.WorkspaceSvg,
+    targetWorkspace: Blockly.WorkspaceSvg,
+    json: Blockly.utils.toolbox.LabelInfo
+  ) {
+    super(workspace, targetWorkspace, json, true);
     this.extensionId = json["id"];
 
     const heightDelta = 40 - this.height;
@@ -76,7 +71,7 @@ export class StatusIndicatorLabel extends Blockly.FlyoutButton {
     const text = this.getSvgRoot().querySelector("text");
     const previousY = Number(text.getAttribute("y"));
 
-    text.setAttribute("y", previousY + heightDelta / 2);
+    text.setAttribute("y", `${previousY + heightDelta / 2}`);
 
     const statusButtonWidth = 30;
     const marginX = 20;
@@ -88,7 +83,6 @@ export class StatusIndicatorLabel extends Blockly.FlyoutButton {
       ? marginX - flyoutWidth + statusButtonWidth
       : (flyoutWidth - statusButtonWidth - marginX) / workspace.scale;
 
-    /** @type {SVGElement} */
     this.imageElement = Blockly.utils.dom.createSvgElement(
       "image",
       {
@@ -140,31 +134,25 @@ export class StatusIndicatorLabel extends Blockly.FlyoutButton {
 
   /**
    * Set the source URL of the image for the button.
-   * @param {?string} src New source.
+   * @param src New source.
    * @package
    */
-  setImageSrc(src) {
-    if (src === null) {
-      // No change if null.
-      return;
-    }
-    this.imageSrc = src;
+  setImageSrc(src: string) {
     if (this.imageElement) {
       this.imageElement.setAttributeNS(
         "http://www.w3.org/1999/xlink",
         "xlink:href",
-        this.imageSrc || ""
+        src
       );
     }
   }
 
   /**
    * Gets the extension state. Overridden externally.
-   * @param {string} extensionId The ID of the extension in question.
-   * @return {Blockly.StatusButtonState} The state of the extension.
-   * @public
+   * @param extensionId The ID of the extension in question.
+   * @return The state of the extension.
    */
-  getExtensionState(extensionId) {
+  getExtensionState(extensionId: string): StatusButtonState {
     return StatusButtonState.NOT_READY;
   }
 
@@ -180,7 +168,7 @@ export class StatusIndicatorLabel extends Blockly.FlyoutButton {
 /**
  * Set of available states for a status indicator.
  */
-export const StatusButtonState = {
-  READY: "ready",
-  NOT_READY: "not ready",
-};
+export enum StatusButtonState {
+  READY = "ready",
+  NOT_READY = "not ready",
+}

package/src/{status_indicator_label_flyout_inflater.js → status_indicator_label_flyout_inflater.ts}

@@ -5,7 +5,7 @@
  */
 
 import * as Blockly from "blockly/core";
-import { StatusIndicatorLabel } from "./status_indicator_label.js";
+import { StatusIndicatorLabel } from "./status_indicator_label";
 
 /**
  * Flyout inflater responsible for creating status indicator labels.
@@ -13,17 +13,19 @@ import { StatusIndicatorLabel } from "./status_indicator_label.js";
 class StatusIndicatorLabelFlyoutInflater extends Blockly.LabelFlyoutInflater {
   /**
    * Creates a status indicator label on the flyout from the given state.
-   * @param {!Object} state JSON representation of a status indicator label.
-   * @param {!Blockly.WorkspaceSvg} flyoutWorkspace The workspace to create the
+   * @param state JSON representation of a status indicator label.
+   * @param flyoutWorkspace The workspace to create the
    *     label on.
-   * @returns {!StatusIndicatorLabel} The newly created status indicator label.
+   * @returns The newly created status indicator label.
    */
-  load(state, flyoutWorkspace) {
+  load(
+    state: Blockly.utils.toolbox.LabelInfo,
+    flyoutWorkspace: Blockly.WorkspaceSvg
+  ): StatusIndicatorLabel {
     const label = new StatusIndicatorLabel(
       flyoutWorkspace,
       flyoutWorkspace.targetWorkspace,
-      state,
-      true
+      state
     );
     label.show();
     return label;